API 개요

Studio 서버는 웹 UI가 쓰는 것과 같은 REST API를 노출합니다. 이 문서는 그 API를 직접 호출하려는 통합 개발자를 위한 것입니다.

기준 주소

모든 경로는 Studio 서버 주소 아래의 /api 로 시작합니다.

https://<studio-host>/api/...

세션 토큰을 헤더로 보냅니다.

Authorization: Bearer <token>

토큰이 없거나 만료되면 서버가 401 을 돌려줍니다. 웹 UI는 401을 받으면 저장된 토큰을 지우고 로그인 화면으로 돌아갑니다. 직접 호출할 때도 같은 처리를 권합니다 — 401은 재시도로 풀리지 않습니다.

성공 응답은 data 봉투에 담겨 옵니다.

{
  "data": { "id": "prj_01H...", "name": "라인 모니터" }
}

실패 응답은 errors 배열을 담습니다. 첫 번째 항목의 message 가 사람이 읽을 메시지입니다.

{
  "errors": [
    { "code": "project_not_found", "message": "프로젝트를 찾을 수 없습니다." }
  ]
}

클라이언트는 HTTP 상태와 errors[0].message 를 함께 보는 것이 안전합니다. 서버가 메시지를 주지 않는 경우가 있어 웹 UI는 그때만 자체 폴백 문구를 씁니다.

에이전트가 작업하는 동안의 진행 상황은 스트리밍으로 옵니다. 대화(/api/session/{id}/message, /api/ask)와 알림(/api/notifications/stream)이 여기 해당합니다.

이벤트는 다음 일곱 가지입니다.

done 또는 error 가 올 때까지 읽으면 됩니다.

이미지 같은 첨부는 base64로 인라인 전송합니다.

{
  "name": "설비사진.png",
  "mime": "image/png",
  "dataBase64": "iVBORw0KGgo..."
}