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

# REST API 개요

> 서버용 API 키로 통화를 만들고, 목록·결과를 조회하고, 진행 중인 통화를 다른 번호로 전환하거나 종료해요.

## 할 수 있는 일

백엔드나 CRM에서 HTTP 요청으로 Tello 통화를 시작해요. 운영에 반영한 에이전트나 크루가
대화를 맡고, 애플리케이션은 통화 생성·조회·전환·종료를 제어해요. 턴마다 직접 답변을 만들려면
[SDK](https://docs.telloai.io/developer/sdk/quickstart.md)나 [A2A](https://docs.telloai.io/developer/a2a/inbound.md)를 쓰세요.

```text Base URL theme={null}
https://api.telloai.io/v1
```

| 메서드 · 경로 | 할 수 있는 일 | 성공 응답 |
| - | - | - |
| `POST /calls` | [통화 생성](https://docs.telloai.io/developer/rest/create-call.md) | `201` + 통화 객체 |
| `GET /calls` | [통화 목록](https://docs.telloai.io/developer/rest/list-calls.md) | `200` + `{ data, nextCursor }` |
| `GET /calls/{callId}` | [통화 상세](https://docs.telloai.io/developer/rest/get-call.md) | `200` + 통화 객체 |
| `POST /calls/{callId}/end` | [통화 종료 요청](https://docs.telloai.io/developer/rest/end-call.md) | `202` + 접수 시점의 통화 객체 |
| `POST /calls/{callId}/transfer` | [통화 전환 요청](https://docs.telloai.io/developer/rest/transfer-call.md) | `202` + 접수 시점의 통화 객체 |
| `GET /agents` | [에이전트 목록](https://docs.telloai.io/developer/rest/targets.md#에이전트-목록) | `200` + `{ data }` |
| `GET /crews` | [크루 목록](https://docs.telloai.io/developer/rest/targets.md#크루-목록) | `200` + `{ data }` |

## 인증

포털 **개발자 연동 › API 키**에서 키를 발급해요. MCP·SDK·A2A에서 쓰던 **같은 서버용 키**를
그대로 쓸 수 있어요. 키는 계정을 인증하고, 통화에 쓸 대상은 생성 요청마다 `agentId`나
`crewId`로 지정해요.

모든 REST 엔드포인트에 아래 헤더를 붙이세요.

```http theme={null}
Authorization: Bearer <API_KEY>
```

```bash 에이전트 목록으로 인증 확인 theme={null}
curl "https://api.telloai.io/v1/agents" \
  --header "Authorization: Bearer <API_KEY>"
```

키가 없거나 잘못됐거나 폐기됐을 때, 또는 계정이 비활성일 때는 모두 `401 unauthenticated`가
와요. 이유를 더 세분해서 알려 주지는 않아요. 키를 폐기하면 다음 REST 요청부터 거절돼요.

> [!WARNING]
>
> 브라우저·모바일 앱 코드나 공개 저장소에 키를 넣지 마세요. 키로 인증한 계정의 통화를
> 조회하고 제어할 수 있어요. 이미 시작한 통화는 키를 폐기하는 것만으로 끝나지 않으니,
> 필요하면 [통화 종료](https://docs.telloai.io/developer/rest/end-call.md)를 따로 요청하세요.

## 시작하기 전에

발신에는 크레딧, 남은 동시 발신 회선, 수신번호 인증, 발신번호 설정이 필요해요.
[연동 준비](https://docs.telloai.io/developer/overview.md)에서 계정 조건을 확인하세요.

[대상 목록](https://docs.telloai.io/developer/rest/targets.md)에서 에이전트나 크루 id를 고른 뒤 통화를 생성해요.
대상은 **운영에 반영된 판**이 있어야 해요. REST API는 기본 대상을 자동으로 고르지 않아요.

## 공통 규격

* 요청·응답은 JSON이고 필드 이름은 **camelCase**예요. 본문을 보낼 때는
  `Content-Type: application/json`을 붙이세요.
* 통화 id는 `c_12345`처럼 **`c_`와 숫자**로 이루어진 문자열이에요. 숫자 부분을 별도 정수로
  변환하지 말고 받은 문자열 그대로 저장하고 보내세요.
* 에이전트·크루 id는 응답에서 숫자로 된 **문자열**로 와요. 생성 요청에서는 양의 정수나
  그 정수를 나타내는 문자열을 쓸 수 있어요.
* 시각은 ISO-8601 형식이에요. 응답은 시간대를 명시하고, 목록 날짜 조건은
  [날짜·시간 필터](https://docs.telloai.io/developer/rest/list-calls.md#날짜시간-필터) 규칙을 따라요.
* 아직 만들어지지 않았거나 제공되지 않는 통화 필드는 `null`이에요. 요약이 없다는 이유로
  통화가 진행 중인 것은 아니니, 진행 여부는 `status`로 판단하세요.

## 오류 응답

오류는 아래 봉투로 와요. **분기는 `error`와 HTTP 상태 코드로 하세요.** `message`는 표시용이고
문구가 달라질 수 있어요.

```json 401 예시 theme={null}
{
  "statusCode": 401,
  "message": "A valid API key is required",
  "error": "unauthenticated",
  "data": null
}
```

| 필드 | 설명 |
| - | - |
| `statusCode` | HTTP 상태 코드예요 |
| `message` | 오류를 설명하는 표시용 문장이에요 |
| `error` | 애플리케이션이 분기할 고정 오류 코드예요 |
| `data` | 보통 `null`이에요. `missing_variables`일 때만 `missingVariables` 목록이 와요 |

전체 코드와 대처 방법은 [REST 오류](https://docs.telloai.io/developer/rest/errors.md)에 있어요.

## 응답 이후의 통화

`201`은 발신 요청을 수락했다는 뜻이지, 상대가 받았거나 통화가 끝났다는 뜻이 아니에요.
**응답을 받은 뒤 HTTP 연결을 닫아도 통화는 계속돼요.** 상태와 결과는 통화 상세로 확인하고,
중단할 때는 종료 엔드포인트를 호출하세요.

네트워크 문제로 생성 요청을 다시 보낼 수 있다면 처음부터
[`Idempotency-Key`](https://docs.telloai.io/developer/rest/create-call#중복-발신-방지)를 붙이세요.
`502 call_outcome_unknown`을 받았다면 통화가 이미 시작됐을 수 있어요.
**목록을 확인하지 않고 새 키로 다시 발신하지 마세요.**

> [!WARNING]
>
> 예제의 통화 생성 요청도 실제 전화를 걸고 크레딧을 사용해요. 통제된 테스트 수신번호로만
> 시험하세요.

## 관련 문서

> **[통화 생성](https://docs.telloai.io/developer/rest/create-call.md)**
>
> 대상을 지정하고 중복 발신 없이 통화를 시작해요

> **[통화 상세](https://docs.telloai.io/developer/rest/get-call.md)**
>
> 상태·전사·요약·차감 크레딧을 확인해요

> **[대상 목록](https://docs.telloai.io/developer/rest/targets.md)**
>
> 통화에 쓸 에이전트와 크루 id를 찾아요

> **[오류](https://docs.telloai.io/developer/rest/errors.md)**
>
> 오류 코드별로 요청 수정과 재시도 방법을 확인해요


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.