Agent API v1

네 에이전트를 Thinkly에 몇 분 안에 연결하세요.

하나의 API 키로 메모, 링크, 마크다운, 프로젝트를 Thinkly에 보낼 수 있습니다. 저장한 컨텍스트를 페이지와 다시 쓰는 초안으로 연결하는 것도 같은 API로 시작할 수 있습니다.

First request
curl https://thinkly.pluglab.ai/api/agent/clips \
  -X POST \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: clip-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "주간 인사이트",
    "text": "오늘 리서치에서 남길 만한 최종 답변입니다."
  }'
Clips
POST /api/agent/clips
Ingest
POST /api/agent/ingest
Upload
POST /api/agent/upload
Projects
POST /api/agent/projects

무엇을 할 수 있나

에이전트 출력을 바로 클립으로 저장

좋은 답변 하나만 저장할 수도 있고, 중요한 결과를 Thinkly로 계속 보내둘 수도 있습니다.

링크, 텍스트, 마크다운을 한 번에 ingest

관련 있는 항목들을 한 capture로 묶어 나중에 다시 쓰기 쉽게 남길 수 있습니다.

페이지를 만들고 드래프트를 생성

먼저 컨텍스트를 페이지로 정리하고, 준비가 되면 드래프트를 생성하세요.

외부 워크플로에서 프로젝트 생성

에이전트가 시작한 흐름을 Thinkly 프로젝트로 열고, 이후 정리는 제품 안에서 이어갈 수 있습니다.

Quickstart

1

Thinkly에 로그인한 뒤 Settings → API keys에서 scoped API 키를 만드세요.

2

모든 요청에 Bearer 토큰으로 키를 전달하고, write 요청에는 Idempotency-Key도 함께 넣으세요.

3

먼저 clip 또는 ingest 하나로 시작하고, 그 다음 pages, draft generation, upload, projects로 확장하세요.

인증

Thinkly Agent API v1은 개인 API 키를 사용합니다. integration별 scoped key를 만들 수 있고, 서버 쪽에서만 보관하며 Bearer 토큰으로 전달해야 합니다.

curl https://thinkly.pluglab.ai/api/agent/clips \
  -X POST \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: clip-001' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "주간 인사이트",
    "text": "오늘 리서치에서 남길 만한 최종 답변입니다."
  }'
  • clips, ingest, upload, pages, generation, projects 범위별로 scoped key를 만들 수 있습니다.
  • 권장 scope 예시: clips:write, ingest:write, upload:write, pages:read, pages:generate, projects:write
  • 키 생성과 revoke는 Settings → API keys에서 할 수 있습니다.

크레딧과 리밋

Agent API도 제품과 같은 요금제 제한을 따릅니다. 별도 agent 전용 quota가 아니라, AI 작업은 같은 credit ledger를 사용합니다.

  • POST /api/agent/ingest 는 item별로 AI credits를 차감합니다: text 1, markdown 1, url 2
  • POST /api/agent/pages/:id/generate 는 custom 6, template set 15 credits를 사용합니다.
  • 프로젝트 생성은 앱과 같은 활성 프로젝트 제한을 그대로 따릅니다.

Idempotent write

쓰기 요청은 Idempotency-Key를 지원합니다. 같은 요청을 같은 키로 다시 보내면 저장된 결과를 반환하고, 다른 body로 같은 키를 재사용하면 409를 반환합니다.

curl https://thinkly.pluglab.ai/api/agent/projects \
  -X POST \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: project-2026-04-launch' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "4월 런치 플랜",
    "template": "goal_milestones"
  }'

핵심 엔드포인트

POST/api/agent/clips

클립 하나 저장

메모, 링크, 저장할 답변 하나를 보낼 때 쓰면 됩니다.

{
  "title": "저장할 답변",
  "text": "다시 쓸 가치가 있는 최종 요약입니다.",
  "tags": ["research", "launch"]
}
POST/api/agent/ingest

배치 ingest

텍스트, URL, 마크다운을 한 번에 보내고 같은 capture로 묶어둘 수 있습니다.

{
  "items": [
    { "type": "url", "url": "https://example.com/article" },
    { "type": "markdown", "title": "메모", "text": "# 핵심\n- 하나\n- 둘" }
  ]
}
POST/api/agent/upload

에이전트 facade로 파일 업로드

에이전트가 파일 첨부를 보내야 할 때도 같은 Agent API 표면에서 multipart 업로드를 처리할 수 있습니다.

curl https://thinkly.pluglab.ai/api/agent/upload \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: upload-001' \
  -F 'file=@notes.md'
POST/api/agent/pages/:id/generate

페이지에서 드래프트 생성

저장한 clip들을 page로 정리한 뒤, 그 page를 바탕으로 초안을 생성할 때 사용합니다.

{
  "mode": "custom",
  "prompt": "이 페이지를 발행 가능한 짧은 브리프로 바꿔주세요."
}
POST/api/agent/projects

프로젝트 생성

이름, 템플릿, 상태를 포함해 외부 에이전트에서 Thinkly 프로젝트를 열 수 있습니다.

{
  "name": "4월 런치 플랜",
  "template": "goal_milestones",
  "icon": "🚀"
}
POST/api/agent/projects/:id/items

프로젝트 stage에 아이템 추가

에이전트 워크플로에서 clip, page, draft, published 항목을 Thinkly 프로젝트 stage에 바로 넣습니다.

{
  "stage": "clip",
  "referenceId": "clip_123"
}

공통 응답 형식

Agent API v1은 성공과 실패를 같은 envelope으로 반환해서, 에이전트가 일관되게 처리할 수 있게 합니다.

{
  "success": true,
  "data": {
    "id": "clip_123",
    "title": "저장할 답변"
  },
  "error": null
}

OpenClaw, Hermes, 커스텀 에이전트를 위한 구조

이미 OpenClaw를 쓰고 있다면 거기서 시작하는 게 가장 빠릅니다. Hermes나 자체 에이전트를 붙일 때는 clips와 ingest부터 시작하고, 이후 pages, generation, projects를 추가하세요.

어떤 연결 방식이 맞는지

가장 빠르게 시작하려면 OpenClaw

명령과 설정 가이드가 이미 준비된 OpenClaw 흐름을 쓰면, 직접 API 클라이언트를 짜기 전에 바로 작동하는 연동을 시작할 수 있습니다.

OpenClaw 가이드 열기

커스텀 워크플로가 필요하면 API

Hermes나 자체 에이전트가 clips 저장, batch ingest, pages 생성, projects 생성까지 직접 다뤄야 한다면 Agent API v1로 가는 게 맞습니다.

랜딩 개요 보기

엔드포인트별 예제 레퍼런스

각 엔드포인트를 펼치면 request body, response 예제, 추천 사용 맥락을 바로 볼 수 있습니다.

POST/api/agent/clips클립 하나 저장
Request body
{
  "title": "저장할 답변",
  "text": "다시 쓸 가치가 있는 최종 요약입니다.",
  "tags": ["research", "launch"]
}
Response
{
  "success": true,
  "data": {
    "id": "clip_123",
    "title": "저장할 답변",
    "text": "다시 쓸 가치가 있는 최종 요약입니다."
  },
  "error": null
}
Notes
  • Hermes나 자체 에이전트에서 가장 먼저 붙이기 좋은 엔드포인트입니다.
  • 좋은 답변 하나씩 저장할 때 가장 단순합니다.
POST/api/agent/ingest배치 ingest
Request body
{
  "items": [
    { "type": "url", "url": "https://example.com/article" },
    { "type": "markdown", "title": "메모", "text": "# 핵심\n- 하나\n- 둘" }
  ]
}
Response
{
  "success": true,
  "data": {
    "captureBatchId": "batch_123",
    "created": [
      { "id": "clip_1", "title": "https://example.com/article", "url": "https://example.com/article" },
      { "id": "clip_2", "title": "메모", "url": null }
    ],
    "failed": []
  },
  "error": null
}
Notes
  • 에이전트가 여러 항목을 한 번에 보낼 때 가장 적합합니다.
  • text, url, markdown를 한 요청 안에서 함께 다룰 수 있습니다.
  • 이 경로는 item별 AI credits를 차감하고, credit 부족 시 항목별 failed 결과를 반환합니다.
POST/api/agent/upload에이전트 facade로 파일 업로드
Request body
curl https://thinkly.pluglab.ai/api/agent/upload \
  -H 'Authorization: Bearer tk_your_api_key' \
  -H 'Idempotency-Key: upload-001' \
  -F 'file=@notes.md'
Response
{
  "success": true,
  "data": {
    "id": "clip_upload_123",
    "title": "notes.md"
  },
  "error": null
}
Notes
  • 파일 자체를 보내야 할 때 이 경로를 사용하면 됩니다.
  • scoped key와 idempotency도 업로드에 그대로 적용됩니다.
  • 내부 웹 전용 upload가 아니라 Agent API facade입니다.
POST/api/agent/pages/:id/generate페이지에서 드래프트 생성
Request body
{
  "mode": "custom",
  "prompt": "이 페이지를 발행 가능한 짧은 브리프로 바꿔주세요."
}
Response
{
  "success": true,
  "data": {
    "jobId": "draft_123",
    "type": "page_generation",
    "status": "completed",
    "result": {
      "draftId": "draft_123"
    }
  },
  "error": null
}
Notes
  • 현재 v1에서는 completed 상태의 lightweight job envelope을 반환합니다.
  • clips를 먼저 page로 정리한 뒤 호출하는 것이 맞습니다.
  • 드래프트 생성은 앱과 같은 AI credits를 사용합니다.
POST/api/agent/projects프로젝트 생성
Request body
{
  "name": "4월 런치 플랜",
  "template": "goal_milestones",
  "icon": "🚀"
}
Response
{
  "success": true,
  "data": {
    "id": "project_123",
    "name": "4월 런치 플랜",
    "template": "goal_milestones"
  },
  "error": null
}
Notes
  • 단일 clip보다 긴 흐름을 운영할 때 적합합니다.
  • 마일스톤형, 보드형 워크플로의 시작점으로 쓰기 좋습니다.
  • 프로젝트 생성은 앱과 같은 활성 프로젝트 제한을 따릅니다.
POST/api/agent/projects/:id/items프로젝트 stage에 아이템 추가
Request body
{
  "stage": "clip",
  "referenceId": "clip_123"
}
Response
{
  "success": true,
  "data": {
    "id": "project_item_123",
    "stage": "clip",
    "referenceId": "clip_123"
  },
  "error": null
}
Notes
  • columnId를 생략하면 Thinkly가 해당 stage의 첫 workflow column을 자동으로 찾습니다.
  • clip이나 page를 만든 직후 프로젝트 플로우에 이어 붙일 때 가장 자연스럽습니다.

현재 v1 범위

  • 초기 연동용 Private Agent API이며, 완전한 공개 플랫폼 버전은 아직 아닙니다.
  • scoped API key, idempotency key, upload facade, project item insert가 v1에 포함됩니다.
  • generation job은 기존 Thinkly draft generation을 감싼 lightweight job wrapper를 사용합니다.

첫 요청 하나만 성공시키고, 그 다음 재사용 흐름으로 확장하세요.

가장 좋은 첫 연동은 단순합니다. 저장할 답변 하나, 링크 하나, 마크다운 메모 하나를 Thinkly에 보내고, 그 결과를 pages와 drafts로 이어가세요.

첫 요청 보기OpenClaw 가이드 열기