> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tiro.ooo/llms.txt
> Use this file to discover all available pages before exploring further.

# API 개요

> AI 기반 노트 작성을 위한 Tiro API 개요

Tiro API로 노트, 전사, 요약, 폴더에 프로그래밍 방식으로 접근할 수 있어요.

## Base URL

모든 API 요청은 다음 주소로 보내세요.

```
https://api.tiro.ooo
```

## 워크스페이스

모든 Tiro API 요청은 하나의 **워크스페이스** 안에서 동작해요. API 키는 워크스페이스 하나에 한정되며, 그 워크스페이스의 리소스 — 노트, 전사, 요약, 폴더 — 에만 닿아요. 키가 다른 워크스페이스로 넘어가는 일은 없어요.

`GET /v1/external/workspaces`를 호출하면 계정이 접근할 수 있는 워크스페이스 목록을 받아요. 각 항목에는 `guid`, `name`, `isWikiEnabled`가 담겨 있어요. `GET /v1/external/workspaces/me`를 호출하면 현재 키가 매핑된 워크스페이스를 확인할 수 있어요.

워크스페이스 단위 리소스는 `workspaceGuid`를 노출해요. 폴더 엔드포인트는 이 값을 경로로 받아요 — `POST /v1/external/workspaces/{workspaceGuid}/folders`는 특정 워크스페이스 안에 폴더를 만들어요. 통합이 여러 워크스페이스에 걸쳐 있다면 워크스페이스마다 키를 하나씩 발급하세요.

## Rate Limit

공정한 사용과 시스템 안정성을 위해 Tiro API는 API Key 하나당 60초에 600 요청까지 허용해요. 초과하면 `429` 응답과 함께 다시 시도할 시점을 알려주는 `Retry-After`·`X-RateLimit-*` 헤더를 받아요.

### Rate Limit 초과

rate limit을 초과하면 `429 Too Many Requests` 응답을 받아요.

```json theme={"system"}
{
  "error": {
    "code": 429001,
    "message": "Rate limit exceeded. Try again in 60 seconds",
    "detail": "Limit of 600 requests per 60 seconds exceeded"
  }
}
```

## 응답 형식

모든 API 응답은 일관된 JSON 형식을 따라요.

### 성공 응답 (목록)

```json theme={"system"}
{
  "content": [...],
  "nextCursor": "opaque-cursor-string"
}
```

### 성공 응답 (단일 리소스)

```json theme={"system"}
{
  "id": "resource-id",
  "createdAt": "2024-01-01T00:00:00Z",
  ...
}
```

### 에러 응답

에러에는 디버깅에 도움이 되는 상세 정보가 포함돼요.

```json theme={"system"}
{
  "error": {
    "code": 400000,
    "message": "Human readable error message",
    "detail": null
  }
}
```