본 문서는 영어 원본을 기계 번역한 것입니다. 번역본과 영어 원본 사이에 내용이 상충할 경우 영어 원본이 우선합니다. 영어 원본 보기

공개 API

Caiioo에는 에이전트 실행, 도구 관리, 작업 예약 등 모든 것을 프로그래밍 방식으로 제어할 수 있는 REST API가 포함되어 있습니다. API는 데스크톱 앱과 브라우저 브리지를 구동하는 동일한 로컬 서버에서 실행됩니다.

기본 URL: http://localhost:3847/v1

인증: 두 가지 인증 방식이 있으며, 둘 다 설정의 API 토글에 의해 제어됩니다:

외부 소비자용 (스크립트, 통합, curl): 설정 > API 액세스에서 API 액세스 토큰을 설정한 후 Bearer 토큰으로 사용하세요:

curl -H \"Authorization: Bearer YOUR_API_TOKEN\" http://localhost:3847/v1/providers

로컬 앱용 (자동): Caiioo 데스크톱 앱, 브라우저 확장 프로그램 및 모바일 앱은 기존 릴레이 인증 헤더(x-relay-auth, 대소문자 구분 없음)를 통해 자동으로 인증됩니다. 수동 설정이 필요 없으며 앱이 배후에서 이를 처리합니다. 릴레이 인증 요청은 이미 신뢰된 상태이므로 공개 API 활성화 토글을 우회하며, Bearer 토큰 요청만 토글의 제어를 받습니다.

설정:

Caiioo 설정 > API 액세스를 엽니다
공개 API 활성화를 켭니다
API 액세스 토큰을 설정합니다 (원하는 문자열 — 비밀번호처럼 취급하세요)
모든 API 요청에 해당 토큰을 사용합니다

API는 localhost 및 개인 릴레이를 통해 사용할 수 있습니다. 현재 상태 및 설정 지침은 GET /v1/auth/info(인증 불필요)를 확인하세요.

속도 제한: 모든 /v1/* 요청은 클라이언트 IP당 속도가 제한됩니다 — 읽기용 GET 요청은 분당 100회, 쓰기용(POST / PATCH / DELETE) 합산 분당 30회입니다. 제한 초과 시 429 에러가 발생합니다. 웹훅 전송(POST /v1/webhooks/:id)은 Bearer 인증이 필요 없으며 이러한 제한의 영향을 받지 않습니다.

프로필

단일 장치에 여러 사용자 프로필(예: 개인용 + 업무용)을 보유할 수 있습니다. API를 통해 외부 스크립트는 사용 가능한 프로필을 검사하고 다른 작업을 수행하기 전에 활성 프로필을 전환할 수 있습니다. 프로필 생성, 업데이트 및 삭제는 의도적으로 공개 API를 통해 노출되지 않습니다. 이러한 흐름은 앱의 온보딩 UI에 속합니다.

프로필 목록 조회:

GET /v1/profiles

삭제되지 않은 프로필당 하나의 항목이 포함된 { profiles: [...] }를 반환합니다. 각 항목에는 id, name, email, avatarUrl, tier, accessibleModes, license, organization, preferences, onboardingComplete, createdAt, lastAccessedAt이 포함됩니다. 토큰 포함 필드(serviceCredentials, oauthConnections) 및 동기화 내부 정보(vectorClock, lastModifiedBy)는 제외됩니다. OAuth 연결을 검사하려면 /v1/connectors를 사용하세요.

활성 프로필 가져오기:

GET /v1/profiles/active

현재 이 서버에서 사용 중인 프로필에 대한 { profile }을 반환합니다. 프로필 범위로 지정된 모든 /v1/* 리소스(스레드, 첨부 파일, 설정, 스킬)는 이 프로필을 대상으로 작동합니다.

활성 프로필 전환:

PUT /v1/profiles/active
Content-Type: application/json

{ "profileId": "목록에서 가져온 사용자 UUID" }

새로 활성화된 프로필에 대한 { profile }을 반환합니다. ID가 알려진 프로필이 아닌 경우 404를 반환합니다.

Providers & Models

어떤 LLM 제공업체가 구성되어 있고 어떤 모델을 사용할 수 있는지 확인하십시오.

제공업체 목록:

GET /v1/providers

지원되는 모든 제공업체 유형을 반환합니다. 현재: anthropic, openai, google, openrouter, ollama, poe, mlx, perplexity, baseten, cloudflare. 각 항목에는 type, displayName, icon, requiresApiKey, hasApiKey 및 아래의 플래그가 포함된 capabilities 객체가 포함됩니다.

기능 플래그	의미
`supportsVision`	제공업체가 이미지 입력을 수락할 수 있음
`supportsPdfFile`	제공업체가 원본 PDF 파일 콘텐츠 블록을 기본적으로 수락할 수 있음
`supportsToolCalling`	제공업체가 함수/도구 호출(tool calling)을 지원함
`supportsStreaming`	제공업체가 토큰을 점진적으로 스트리밍함
`supportsExtendedThinking`	제공업체가 추론/생각(thinking) 예산을 노출함
`supportsPromptCaching`	제공업체가 프롬프트 캐싱 지시어를 지원함
`nativeReasoningBlocks`	제공업체가 생각을 (텍스트가 아닌) 기본 메시지 블록으로 출력함
`requiresThoughtSignature`	제공업체가 서명된 생각 토큰을 다시 에코(echo)하도록 요구함

기능 플래그는 각 제공업체 클래스의 readonly capabilities 필드(src/shared/providers/*-provider.ts 참조)를 반영하며 drift sentinel 테스트에 의해 검증됩니다. 이 매트릭스를 하드코딩하기보다는 런타임에 이 엔드포인트를 호출하십시오.

BYOK 제공업체 관련 참고 사항:

perplexity는 선별된 Sonar 모델 목록을 노출합니다 (Perplexity에는 공개된 /models 엔드포인트가 없습니다).
cloudflare (AI Gateway)는 BYOK 및 멀티 벤더 방식입니다. 모델 목록은 사용자의 게이트웨이 구성에 의해 결정되며 /v1/providers/cloudflare/models에서 빈 배열로 반환됩니다. 사용자 본인의 게이트웨이 카탈로그를 사용하십시오.

제공업체별 모델 목록:

GET /v1/providers/openrouter/models

해당 제공업체의 모델 카탈로그를 반환합니다. 각 모델에는 id, displayName 및 가능한 경우 contextLength가 포함됩니다. 제공업체에 API 키가 없거나 업스트림 카탈로그에 연결할 수 없는 경우 503을 반환합니다.

모든 제공업체 통합 카탈로그:

GET /v1/models

구성된 모든 제공업체의 모델을 하나의 목록으로 병합합니다. API 키가 없는 제공업체는 건너뛰고 warnings에 나열됩니다.

에이전트

에이전트는 Caiioo의 핵심입니다. 각 에이전트는 하나의 모드이며, 자체 시스템 프롬프트, 도구, 변수 및 스킬을 가진 구성된 페르소나입니다.

모든 에이전트 목록:

GET /v1/agents

기본 제공 에이전트(쇼핑, 업무, 일반)와 직접 만든 커스텀 에이전트를 반환합니다. 각 에이전트에는 source: \"builtin\" 또는 source: \"custom\" 태그가 붙습니다.

커스텀 에이전트 생성:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"리서치 에이전트\",
    \"description\": \"웹을 검색하고 결과를 요약합니다\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"당신은 리서치 어시스턴트입니다. 항상 출처를 인용하세요.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

생성된 에이전트와 함께 201을 반환합니다. 동기화를 위해 벡터 클락이 자동으로 첨부됩니다.

에이전트 업데이트:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"리서치 에이전트\", \"description\": \"업데이트된 설명\" } }

기존 에이전트에 패치를 병합하고 벡터 클락을 올립니다. 기본 제공 에이전트는 403을 반환합니다(읽기 전용).

에이전트 삭제:

DELETE /v1/agents/my-research-agent

톰스톤을 통해 소프트 삭제됩니다(기기 간 동기화됨). 204를 반환합니다.

Running Agents

이것은 핵심 기능입니다 — 에이전트를 호출하여 메시지를 처리합니다.

Request body — 지원되는 필드

필드	필수 여부	설명
`agentId`	필수	내장 모드 ID (예: `general`) 또는 커스텀 에이전트 ID
`input.message`	필수	사용자 메시지 텍스트
`input.attachments`	선택	이번 턴에 첨부할 첨부 파일 ID 배열 (`/v1/attachments`를 통해 이미 업로드된 파일)
`input.variables`	선택	에이전트의 변수 리졸버(variable resolver)에 병합될 실행별 변수 재정의(overrides)
`input.tabContext`	선택	페이지 컨텍스트로 주입되는 자유 형식 문자열 (브라우저 브릿지에서 사용됨)
`input.messageId`	선택	클라이언트가 제공하는 메시지 ID — 재시도 시 중복 제거에 유용함
`threadId`	선택	계속 진행할 기존 스레드. 생략 시 새 스레드가 생성되어 반환됨
`mode`	선택	`"sync"` 또는 `"async"`. 기본값은 `"async"`

Synchronous Mode

전체 응답을 기다립니다:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "What's the weather in Paris today?" },
  "mode": "sync"
}

에이전트가 완료된 후 { content, usage, status: "completed" }와 함께 200을 반환합니다. 에이전트 오류 발생 시 { error, status: "error" }와 함께 500을 반환합니다. 동기 실행(Sync runs)은 터미널 이벤트가 수신되지 않을 경우 5분 후 status: "error"와 함께 타임아웃됩니다 — 더 오래 걸릴 수 있는 작업은 async + SSE를 사용하세요.

Asynchronous Mode

실행 후 즉시 반환 — 장시간 실행되는 작업에 유용합니다:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Write a 2000-word analysis of renewable energy trends" },
  "mode": "async"
}

즉시 { runId, threadId, status: "running" }와 함께 202를 반환합니다.

상태 폴링(Poll):

GET /v1/runs/{runId}

{ run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }를 반환합니다. 상태는 running, completed, error, 또는 cancelled 중 하나입니다.

실시간 이벤트 스트림 (SSE):

GET /v1/runs/{runId}/events

GENERATION_STARTED, STREAMING_CONTENT, 도구 호출, 서브 에이전트 활동 및 터미널 이벤트(GENERATION_COMPLETE, GENERATION_ERROR, 또는 GENERATION_CANCELLED) 등 모든 에이전트 이벤트를 발생하는 즉시 text/event-stream으로 반환합니다.

터미널 이벤트 이후, 서버는 명시적인 스트림 종료 신호로서 event: terminal과 빈 데이터 페이로드가 포함된 마지막 SSE 프레임을 하나 더 전송한 후 연결을 닫습니다. 클라이언트는 해당 프레임 수신(또는 연결 종료)을 읽기 중단 신호로 처리해야 합니다.

실행이 이미 종료된 이후에 구독하는 경우, 서버는 전체 최종 record를 포함하는 RUN_SNAPSHOT 유형의 프레임을 하나 재생(replay)한 후, event: terminal 신호를 보내고 연결을 닫습니다.

실행 취소:

POST /v1/runs/{runId}/cancel

{ run: { ..., status: "cancelled" } }를 반환합니다.

Threads

Threads는 대화입니다. 모든 에이전트 실행은 Thread 내에서 발생하며, Thread는 세션 간에 유지됩니다. API를 통해 프로그래밍 방식으로 Thread를 나열, 읽기, 생성 및 관리할 수 있습니다.

모든 Thread 목록 조회 (메타데이터 전용):

GET /v1/threads

현재 프로필에 대해 messages가 제외된 { threads: [...] }를 반환합니다 (메시지가 필요한 경우 상세 엔드포인트를 사용하십시오). id, title, createdAt, updatedAt, modeId, archived, 사용 통계 및 설정된 경우 subAgentHistories, anonymizerSnapshot, threadToolApprovals, threadVariables, threadToolOverrides, messagingBinding, scheduledTaskId 등 다른 모든 필드는 유지됩니다. (더 풍부한 페이로드는 API 전용입니다 — WebSocket 사이드바 브로드캐스트는 전송 제한을 유지하기 위해 더 엄격하게 데이터를 제외합니다.)

전체 메시지를 포함한 Thread 조회:

GET /v1/threads/{id}

messages 배열(모든 사용자 메시지, 어시스턴트 응답, 도구 호출 및 도구 결과)을 포함한 전체 Thread를 반환합니다.

메시지만 조회:

GET /v1/threads/{id}/messages

messages 배열만 반환합니다 — 대화 내용만 필요한 경우 전체 Thread 객체보다 가볍습니다.

Thread 생성:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

{ thread }와 함께 201을 반환합니다. 새 Thread는 즉시 사이드바에 나타납니다 (WebSocket 브로드캐스트를 통해). API는 생성 시 앱의 활성 Thread를 자동으로 전환하지 않습니다 — 이를 원할 경우 PUT /v1/threads/active를 별도로 호출하십시오.

Thread 업데이트:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

업데이트 가능한 필드: title, modeId, archived, lastUsedModel. 변경 사항은 실시간으로 사이드바에 브로드캐스트됩니다.

Thread 삭제:

DELETE /v1/threads/{id}

Thread를 소프트 삭제(동기화를 위한 tombstone 처리)합니다. 204를 반환합니다. 삭제된 Thread는 휴지통으로 이동하며 휴지통을 비우기 전까지 복구할 수 있습니다.

활성 Thread:

GET /v1/threads/active            # { threadId } 반환
PUT /v1/threads/active            # Body: { "threadId": "..." }

휴지통 관리:

GET /v1/threads/trash/count       # { count } 반환
POST /v1/threads/trash/empty      # { deletedCount, protectedCount } 반환

보호된 Thread(데이터 보존 토글을 통해 유지됨)는 휴지통 비우기에서 제외됩니다.

API를 통한 대화 이어가기: 기존 Thread에 후속 메시지를 보내려면 Thread ID와 함께 POST /v1/runs를 사용하십시오:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

에이전트는 Thread의 전체 대화 기록을 참조합니다.

첨부 파일

첨부 파일은 스레드에 연결된 파일(스크린샷, PDF, 문서, 업로드된 이미지, 생성된 아티팩트 등)입니다. API를 통해 이를 나열, 업로드, 다운로드 및 관리할 수 있습니다.

모든 첨부 파일 목록 조회 (메타데이터만):

GET /v1/attachments

현재 프로필의 첨부 파일 메타데이터를 반환합니다. 용량이 큰 필드(dataUrl, extractedContent, extractedImages)는 제외되므로, 해당 데이터가 필요한 경우 상세 또는 콘텐츠 엔드포인트를 사용하세요.

특정 스레드의 첨부 파일 목록 조회:

GET /v1/threads/{threadId}/attachments

첨부 파일 메타데이터 조회:

GET /v1/attachments/{id}

extractedContent(OCR 텍스트, 파싱된 마크다운), contentType, fileName, size 및 hasContent 플래그를 포함한 전체 메타데이터를 반환합니다. 원본 바이너리는 포함되지 않으며 /content 엔드포인트를 사용하세요.

첨부 파일 바이너리 다운로드:

GET /v1/attachments/{id}/content

올바른 Content-Type 및 Content-Disposition 헤더와 함께 원본 파일을 반환합니다. 다음과 같이 파일로 저장할 수 있습니다:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

첨부 파일 업로드:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "분기별 보고서",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl은 base64로 인코딩된 데이터 URL입니다. 새로운 첨부 파일 ID와 함께 201을 반환합니다. 첨부 파일은 지정된 스레드에 연결됩니다.

첨부 파일 메타데이터 업데이트:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "업데이트된 설명", "fileName": "new-name.pdf" }

첨부 파일 삭제:

DELETE /v1/attachments/{id}

툼스톤을 통해 소프트 삭제합니다. 204를 반환합니다.

MCP Servers

에이전트에게 외부 도구 및 데이터 소스에 대한 액세스 권한을 부여하는 서버인 MCP (Model Context Protocol) 서버 연결을 관리합니다.

구성된 서버 목록 조회:

GET /v1/mcp-servers

현재 프로필의 모든 MCP 서버 구성을 반환합니다. 민감한 필드(authToken, env, credentialId)는 응답에서 제외됩니다.

서버 구성 조회:

GET /v1/mcp-servers/{id}

새 MCP 서버 추가:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

원격 HTTP 서버의 경우 "command" 대신 "url"을 사용하세요:

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

POST 시 허용되는 선택적 필드: command, args, env, url, description, transportType, authType, authToken, authHeader, headers, specType, specPath, timeoutMs, credentialId, oauthConnectionId, approval. 서버에서 관리하는 필드(customOAuth, hubPackageId, profileId, connectorId, teamPublished, teamOrgId, vectorClock 등)는 API를 통해 설정할 수 없습니다.

서버 업데이트:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

수정 가능한 필드는 POST 허용 목록과 동일합니다 (credentialId 및 oauthConnectionId 포함 — 삭제 후 재생성 없이 OAuth 연결을 교체할 때 유용함). 서버 관리 필드는 읽기 전용으로 유지됩니다.

서버 활성화/비활성화:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

서버 삭제:

DELETE /v1/mcp-servers/{id}

프로세스 관리

로컬 (stdio) MCP 서버의 경우, 서버 프로세스를 직접 관리할 수 있습니다.

실행 중인 프로세스 목록 조회:

GET /v1/mcp-servers/processes

pid, startedAt, running 상태를 포함하여 실행 중인 서버 프로세스를 반환합니다.

서버 시작:

POST /v1/mcp-servers/{id}/start

서버 구성에서 command/args/env를 읽어 프로세스를 생성합니다. 프로세스 상태를 반환합니다.

서버 중지:

POST /v1/mcp-servers/{id}/stop

서버 프로세스를 정상적으로 종료합니다 (SIGTERM 시도 후 실패 시 SIGKILL 사용).

JSON-RPC 메서드 직접 호출:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

서버에 원시 JSON-RPC 2.0 요청을 보내고 결과를 반환합니다. 디버깅이나 도구 API를 통해 노출되지 않은 메서드를 호출할 때 유용합니다.

Tools & Toolkits

에이전트가 사용하는 도구(웹 브라우징, 검색, 캘린더, Gmail, Slate 등)를 탐색하고 호출합니다.

도구 모음(Toolkits) 목록 조회 (그룹화):

GET /v1/toolkits

카테고리(Productivity, Search, Utilities 등)별로 그룹화된 내장 도구와 별도의 도구 모음으로 연결된 모든 MCP 서버 및 해당 액션 목록을 반환합니다.

모든 도구 목록 조회 (단일 리스트):

GET /v1/tools
GET /v1/tools?source=embedded   # 내장 도구만 조회
GET /v1/tools?source=mcp        # MCP 서버 도구만 조회

입력 스키마를 포함한 도구 상세 정보 조회:

GET /v1/tools/calculator

{ tool: { name, displayName, description, source, category, inputSchema, actions?, requiredTier?, requiredRuntimes?, riskTier?, riskExplanation?, requiresApproval? } }를 반환합니다.

필드	의미
`inputSchema`	도구 입력에 대한 JSON Schema — 호출 전 유효성 검사에 사용
`actions`	선택적 하위 액션 (예: Slate의 `read`/`write`); 각 액션은 `id`, `displayName`, `description`, 선택적 `requiredTier`를 가짐
`requiredTier`	최소 사용자 티어 (생략 시 `free`). Public API 호출 시 `free`를 초과하는 티어는 거부됨
`requiredRuntimes`	이 도구를 사용할 수 있는 플랫폼 (`macos`, `ios` 등); 생략 시 모든 플랫폼 지원
`riskTier`	동의 위험 수준: `low` (기본값), `medium`, `high`
`riskExplanation`	`riskTier`가 높은 이유에 대한 설명
`requiresApproval`	도구 호출 시마다 사용자 승인이 필요한 경우 `true` — Public API 호출 시 거부됨

도구 직접 호출:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" }, "threadId": "optional-thread-id" }

{ result }를 반환합니다. 입력값은 도구의 스키마에 따라 유효성이 검사되며, 유효하지 않은 경우 상세 내용과 함께 422 에러를 반환합니다. 도구에 스레드 범위의 컨텍스트(예: 첨부 파일 조회)가 필요한 경우 선택적으로 threadId를 전달하십시오.

제한 사항 — Public API에서 거부되는 항목:

티어 제한 도구 (metadata.requiredTier !== 'free') → 403. 에이전트 루프는 사용자 세션의 티어를 확인하지만, Public API는 전달된 티어 컨텍스트가 없으므로 보수적인 정책에 따라 거부합니다. 대신 적절한 티어를 가진 에이전트와 함께 POST /v1/runs를 사용하십시오.
승인 필수 도구 (metadata.approval.requiresApproval === true) → 403. 승인을 요청할 사용자가 루프에 존재하지 않습니다. (사용자에게 프롬프트를 표시하는) POST /v1/runs를 통해 호출하거나, 앱에서 도구 승인 모드를 approve_all로 설정하여 우회하십시오.
원격 MCP 도구 → 501. /v1/runs를 사용하도록 안내됩니다 (에이전트 서브프로세스 전송 계층이 필요함).

Vision 및 이미지 사용 도구: 먼저 POST /v1/attachments를 통해 업로드한 후, 반환된 attachment ID를 input 내부에 전달하십시오 (예: { "input": { "attachment_id": "att_abc", "prompt": "이 이미지에 무엇이 있나요?" } }). 도구는 threadId를 통해 저장소에서 바이너리를 읽어오며, 바이트 데이터를 인라인으로 직접 전달하지 않습니다.

커넥터

Google, Microsoft, GitHub, Notion, Slack 등 OAuth 통합을 관리합니다.

사용 가능한 통합 찾아보기:

GET /v1/connectors/catalog

이름, 카테고리, 기본 스코프와 함께 등록된 모든 OAuth 제공자를 반환합니다.

연결된 계정 목록:

GET /v1/connectors

현재 프로필의 활성 연결을 반환합니다. 토큰은 절대 노출되지 않으며 메타데이터(제공자, 이메일, 상태, 스코프, 타임스탬프)만 노출됩니다.

단일 연결 조회:

GET /v1/connectors/{id}

하나의 연결에 대한 메타데이터를 반환합니다. 토큰은 노출되지 않습니다.

연결 상태 확인:

POST /v1/connectors/{id}/test

{ health: { status, isTokenExpired, canRefresh } }를 반환합니다.

연결 제거:

DELETE /v1/connectors/{id}

새로운 연결을 생성하려면 앱 UI 또는 /auth/* 경로를 통한 대화형 OAuth 흐름이 필요합니다.

트리거

일일 브리핑, 주간 보고서, 간격 기반 모니터링 등 에이전트가 자동으로 실행되도록 예약합니다.

모든 트리거에는 kind 식별자가 있습니다: schedule (기본값 — 시계에 따라 실행), webhook (외부 서비스가 웹훅 경로로 POST할 때 실행), 또는 messaging (연결된 메시징 어댑터에서 실행 — 예: 채널 필터와 일치하는 Slack/Discord 수신 메시지).

트리거 목록:

GET /v1/triggers

{ triggers: [...] }를 반환합니다. 각 항목에는 kind, 일정 및 종류별 필드(예: 웹훅 트리거의 경우 webhookSecret/webhookPath, 메시징 트리거의 경우 messagingAdapterId/messagingChannelFilter)가 포함됩니다.

단일 트리거 조회:

GET /v1/triggers/{id}

예약된 트리거 생성:

POST /v1/triggers
Content-Type: application/json

{
  \"name\": \"아침 브리핑\",
  \"prompt\": \"읽지 않은 이메일과 오늘 일정을 요약해줘\",
  \"modeId\": \"general\",
  \"schedule\": { \"type\": \"daily\", \"time\": \"08:00\" }
}

지원되는 일정 유형:

{ \"type\": \"interval\", \"minutes\": 60 } — N분마다 (최소 15, 최대 1440)
{ \"type\": \"daily\", \"time\": \"09:00\" } — 매일 특정 시간
{ \"type\": \"weekly\", \"day\": \"mon\", \"time\": \"09:00\" } — 매주
{ \"type\": \"weekdays\", \"time\": \"08:30\" } — 월요일부터 금요일까지
{ \"type\": \"daysOfWeek\", \"days\": [\"mon\", \"wed\", \"fri\"], \"time\": \"10:00\" } — 특정 요일
{ \"type\": \"monthly\", \"dayOfMonth\": 1, \"time\": \"09:00\" } — 매월
{ \"type\": \"manual\" } — API를 통해 실행될 때만

수동으로 트리거 실행:

POST /v1/triggers/{id}/fire

결과 실행에 대한 threadId와 함께 202를 반환합니다.

업데이트 또는 삭제:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

웹훅

웹훅 트리거를 사용하면 외부 서비스(CI/CD, 모니터링, 폼 빌더)가 HTTP를 통해 에이전트 실행을 트리거할 수 있습니다.

웹훅 트리거 생성:

POST /v1/triggers
Content-Type: application/json

{
  \"name\": \"배포 훅\",
  \"prompt\": \"배포가 발생했습니다: {{webhook.body}}\",
  \"modeId\": \"general\",
  \"kind\": \"webhook\"
}

webhookSecret 및 webhookPath와 함께 201을 반환합니다. 페이로드 서명에 필요하므로 비밀 키를 저장하세요.

웹훅 전송:

# 원본 요청 본문의 HMAC-SHA256 계산
SIGNATURE=$(echo -n '{\"repo\":\"my-app\",\"branch\":\"main\"}' | openssl dgst -sha256 -hmac \"$WEBHOOK_SECRET\" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{\"repo\": \"my-app\", \"branch\": \"main\"}

웹훅 엔드포인트는 Bearer 인증이 필요하지 않으며 대신 HMAC 검증을 사용합니다. 실행된 스레드의 threadId와 함께 202를 반환합니다. 트리거 프롬프트의 {{webhook.body}} 자리 표시자는 원본 요청 본문으로 대체됩니다.

메시징 트리거

메시징 트리거는 연결된 메시징 어댑터(예: 커뮤니티 허브를 통해 설치된 Slack 또는 Discord 통합)가 트리거 필터와 일치하는 수신 메시지를 받을 때 실행됩니다. kind: \"messaging\"으로 생성합니다:

POST /v1/triggers
Content-Type: application/json

{
  \"name\": \"멘션 응답기\",
  \"prompt\": \"다음 메시지에 도움이 되는 답장을 해줘: {{message.text}}\",
  \"modeId\": \"general\",
  \"kind\": \"messaging\",
  \"messagingAdapterId\": \"slack-team-acme\",
  \"messagingChannelFilter\": \"#support\"
}

어댑터는 일치하는 이벤트를 트리거로 전달할 책임이 있으며, messagingChannelFilter는 어댑터에 따라 다릅니다.

커스텀 함수

에이전트가 호출할 수 있는 고유한 도구를 만듭니다. 함수는 JavaScript 또는 Python으로 작성되며 샌드박스에서 실행됩니다.

함수 목록 조회:

GET /v1/functions

함수 생성:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "키와 몸무게로 체질량 지수(BMI) 계산",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

JavaScript 함수는 input을 받아 결과를 반환해야 합니다. Python 함수는 result 변수를 설정합니다:

# Python 예시
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

함수 직접 실행:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

보안: JavaScript는 Node의 vm 샌드박스에서 실행됩니다(파일 시스템 또는 네트워크 액세스 불가, 10초 타임아웃). Python은 30초 타임아웃이 있는 서브프로세스로 실행됩니다. 둘 다 실행 전 입력을 검증합니다.

업데이트 또는 삭제:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

스킬

스킬은 에이전트가 참조하고 빈 대화 보기에서 빠르게 실행할 수 있도록 저장된 프롬프트입니다. 허브에서 설치된 스킬(패키지 설치를 통해 관리됨)은 여기에 포함되지 않으며, 사용자가 직접 작성한 스킬만 나열되고 편집할 수 있습니다.

스킬 목록 조회:

GET /v1/skills

활성 프로필에 대해 사용자가 작성한 스킬의 { skills: [...] }를 반환합니다. 삭제 표시된 스킬, 허브 오버레이 및 동기화 섀도우 스킬은 필터링됩니다.

스킬 상세 조회:

GET /v1/skills/{id}

스킬 생성:

POST /v1/skills
Content-Type: application/json

{
  "prompt": "페이지 내용을 3개의 불렛 포인트로 요약해줘.",
  "tags": ["유틸리티", "요약"],
  "isFavorite": true,
  "modes": ["general"],
  "displayName": "빠른 요약",
  "description": "활성 페이지의 3줄 요약"
}

prompt 필드만 필수입니다. modes(선택 사항)는 스킬의 범위를 특정 에이전트 ID로 제한합니다. 모든 모드에 적용하려면 생략하세요. 서버에서 할당된 id, createdAt, updatedAt이 포함된 새 스킬과 함께 201을 반환합니다.

스킬 업데이트:

PATCH /v1/skills/{id}
Content-Type: application/json

{ "prompt": "업데이트된 프롬프트", "isFavorite": false }

수정 가능한 필드: prompt, tags, modes, displayName, description, isFavorite. 허브 오버레이 스킬을 수정하려고 시도하면 404를 반환합니다.

스킬 삭제:

DELETE /v1/skills/{id}

삭제 표시를 통해 소프트 삭제합니다. 204를 반환합니다. 허브 오버레이 스킬은 404를 반환하며, 대신 소스 패키지를 삭제해야 합니다.

워크플로우

여러 에이전트를 DAG(방향성 비순환 그래프)로 오케스트레이션합니다. 가능한 경우 단계를 병렬로 실행하고, 이전 단계의 출력을 다음 단계의 입력으로 전달합니다.

워크플로우 그래프 검증:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "재생 에너지 트렌드 조사" },
      { "id": "analyze", "agentId": "general", "prompt": "경쟁사 가격 조사" },
      { "id": "report", "agentId": "general", "prompt": "다음 내용을 결합하여 보고서 작성: {{outputs.research}} 및 {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

{ valid: true/false, errors: [...] }를 반환합니다. 순환 참조, 중복 ID 및 누락된 종속성 참조를 확인합니다.

워크플로우 실행:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "재생 에너지 트렌드 조사" },
      { "id": "summarize", "agentId": "general", "prompt": "요약: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

{ status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }를 반환합니다.

독립적인 노드(공유 종속성 없음)는 병렬로 실행됩니다. 노드 프롬프트의 {{outputs.nodeId}} 자리표시자는 지정된 상류 노드의 콘텐츠 출력으로 대체됩니다. 각 노드는 전체 에이전트 실행이므로 도구 사용, 웹 브라우징 및 대상 에이전트의 모든 기능을 사용할 수 있습니다.

지식 베이스

문서를 에이전트가 참조할 수 있는 검색 가능한 컬렉션으로 구성합니다.

지식 베이스 목록 조회:

GET /v1/knowledge/bases

지식 베이스 생성:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "연구 논문" }

새로운 베이스 ID와 함께 201을 반환합니다.

지식 베이스에 문서 업로드:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "2026년 재생 에너지 트렌드"
}

dataUrl 필드는 base64로 인코딩된 데이터 URL입니다. 문서 메타데이터와 함께 201을 반환합니다.

지식 베이스 내 문서 목록 조회:

GET /v1/knowledge/bases/{id}/documents

지식 베이스 내 검색:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "재생 에너지" }

파일 이름과 설명을 기반으로 일치하는 문서를 반환합니다. 시맨틱(벡터) 검색은 향후 릴리스에서 제공될 예정입니다.

문서 또는 지식 베이스 삭제:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

에이전트 내보내기 및 가져오기

에이전트를 기기, 팀 또는 커뮤니티 허브 간에 이동 가능한 패키지로 공유하세요.

에이전트 내보내기:

POST /v1/agents/{id}/export

에이전트 정의, 도구 요구 사항, 커넥터 요구 사항 및 트리거 템플릿이 포함된 JSON 패키지를 반환합니다. 동기화 메타데이터는 제거되어 깨끗하고 독립적인 청사진이 됩니다.

에이전트 가져오기:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"리서치 에이전트\", \"description\": \"팀에서 공유함\" },
      \"defaultSettings\": { \"systemPrompt\": \"당신은 리서치를 수행합니다.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

설치된 에이전트와 함께 201을 반환합니다. 기본 제공 또는 기존 에이전트와 ID가 충돌하면 409를 반환합니다.

오류 처리

API는 표준 HTTP 상태 코드를 사용합니다:

코드	의미
`200`	성공
`201`	생성됨
`202`	수락됨 (비동기 작업 시작)
`204`	삭제됨 (콘텐츠 없음)
`400`	잘못된 요청 — 자세한 내용은 `error` 필드를 확인하세요
`401`	권한 없음 — 세션 비밀 키가 누락되었거나 유효하지 않음
`403`	금지됨 — 예: 기본 제공 에이전트를 수정하려고 시도함
`404`	찾을 수 없음
`409`	충돌 — 예: 에이전트 ID가 이미 존재함
`422`	유효성 검사 오류 — 입력이 도구 스키마와 일치하지 않음
`429`	속도 제한 — 인증 섹션의 속도 제한 예산을 참조하세요
`500`	서버 오류 — `error` 필드를 확인하세요
`501`	구현되지 않음 — 기능은 존재하지만 이 방식으로는 사용할 수 없음
`503`	서비스 일시 중지 — 저장소 또는 제공자가 준비되지 않음

모든 오류 응답에는 { "error": "사람이 읽을 수 있는 메시지" }가 포함됩니다.

빠른 시작 예시

에이전트를 생성하고 실행한 뒤 결과를 스트리밍하는 전체 워크플로우입니다.

# 1. 커스텀 에이전트 생성
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "모든 입력을 3개의 불렛 포인트로 간결하게 요약하세요.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. 비동기로 실행
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "https://ko.wikipedia.org/wiki/인공지능 요약해줘" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. 이벤트 스트리밍
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. 공유를 위해 에이전트 내보내기
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.