upstream-twenty/packages/twenty-docs/l/ko/developers/extend/capabilities/apis.mdx

---
title: API
description: REST 또는 GraphQL을 사용해 프로그래밍 방식으로 CRM 데이터를 쿼리하고 수정하세요.
---

import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';

Twenty는 개발자 친화적으로 설계되어 있으며, 맞춤형 데이터 모델에 적합한 강력한 API를 제공합니다. 우리는 여러 통합 요구에 맞는 네 가지 고유한 API 유형을 제공합니다.

## 개발자 우선 접근 방식

Twenty는 귀하의 데이터 모델에 맞는 API를 특별히 생성합니다:

* **긴 ID가 필요하지 않습니다**: 객체 및 필드 이름을 직접 엔드포인트에 사용합니다.
* **표준 및 사용자 정의 객체가 동등하게 처리됩니다**: 내장된 객체와 동일한 API 처리를 사용자 정의 객체에도 제공합니다.
* **전용 엔드포인트**: 각 객체와 필드에 자체 API 엔드포인트가 할당됩니다.
* **맞춤형 문서**: 작업 공간의 데이터 모델에 맞게 특별히 생성됩니다.

<Note>
맞춤형 API 문서는 API 키 생성 후 **설정 → API 및 웹훅**에서 확인할 수 있습니다. Twenty가 사용자 지정 데이터 모델에 맞는 API를 생성하므로, 문서는 귀하의 워크스페이스에 고유합니다.
</Note>

## 두 가지 API 유형

### Core API

`/rest/` 또는 `/graphql/`에서 접근할 수 있습니다.

실제 **레코드**(데이터)로 작업합니다:

* People, Companies, Opportunities 등을 생성, 조회, 업데이트, 삭제합니다.
* 데이터를 쿼리하고 필터링합니다
* 데이터 기록의 관계를 관리합니다.

### 메타데이터 API

`/rest/metadata/` 또는 `/metadata/`에서 접근할 수 있습니다.

**워크스페이스와 데이터 모델** 관리:

* 객체 및 필드를 생성, 수정 또는 삭제합니다.
* 작업 공간 설정을 구성합니다.
* 객체 간 관계를 정의합니다

## REST와 GraphQL

코어 및 메타데이터 API는 REST와 GraphQL 형식으로 제공됩니다:

| 형식          | 사용 가능한 작업                       |
| ----------- | ------------------------------- |
| **REST**    | CRUD, 배치 작업, 업서트                |
| **GraphQL** | 동일 + **배치 업서트**, 한 번의 호출로 관계 쿼리 |

필요에 따라 선택하세요 — 두 형식 모두 동일한 데이터에 접근합니다.

## API 엔드포인트

| 환경         | 기본 URL                    |
| ---------- | ------------------------- |
| **클라우드**   | `https://api.twenty.com/` |
| **셀프 호스팅** | `https://{your-domain}/`  |

## 인증

모든 API 요청에는 헤더에 API 키가 필요합니다:

```
Authorization: Bearer YOUR_API_KEY
```

### API 키 생성

1. **설정 → API 및 웹훅**으로 이동하세요
2. **+ 키 생성**을 클릭하세요
3. 구성:
   * **이름**: 키를 설명하는 이름
   * **만료 날짜**: 키가 만료되는 시점
4. **저장** 클릭
5. **즉시 복사** — 키는 한 번만 표시됩니다

<VimeoEmbed videoId="928786722" title="API 키 생성" />

<Warning>
API 키는 민감한 데이터에 대한 액세스를 부여합니다. 신뢰할 수 없는 서비스와 공유하지 마세요. 유출되었으면 즉시 비활성화하고 새 키를 생성하세요.
</Warning>

### API 키에 역할 할당

보안을 강화하려면 액세스를 제한할 특정 역할을 할당하세요:

1. **설정 → 구성원 → 역할**로 이동하세요
2. 할당할 역할을 클릭하세요
3. **배정** 탭 열기
4. **API 키**에서 **+ API 키에 할당**을 클릭하세요
5. API 키를 선택하세요

키가 해당 역할의 권한을 상속받습니다. 자세한 내용은 [권한](/l/ko/user-guide/permissions-access/capabilities/permissions)을 참조하세요.

### API 키 관리

**재생성**: 설정 → API 및 웹훅 → 키 클릭 → **재생성**

**삭제**: 설정 → API 및 웹훅 → 키 클릭 → **삭제**

## API 플레이그라운드

내장 플레이그라운드를 사용해 브라우저에서 직접 API를 테스트하세요 — **REST**와 **GraphQL** 모두에 대해 사용할 수 있습니다.

### 플레이그라운드에 액세스

1. **설정 → API 및 웹훅**으로 이동하세요
2. API 키 생성(필수)
3. 플레이그라운드를 열려면 **REST API** 또는 **GraphQL API**를 클릭하세요

### 얻을 수 있는 내용

* **대화형 문서**: 귀하의 특정 데이터 모델에 맞게 생성됩니다
* 워크스페이스를 대상으로 실제 API 호출을 실행합니다
* **스키마 탐색기**: 사용 가능한 객체, 필드 및 관계를 탐색합니다
* **요청 빌더**: 자동 완성을 통해 쿼리를 구성합니다

플레이그라운드는 사용자 지정 객체와 필드를 반영하므로 문서는 항상 워크스페이스에 대해 정확합니다.

## 배치 작업

REST와 GraphQL 모두 배치 작업을 지원합니다:

* **배치 크기**: 요청당 최대 60개의 기록
* **작업**: 여러 기록을 생성, 업데이트, 삭제합니다

**GraphQL 전용 기능:**

* **배치 업서트**: 한 번의 호출로 생성하거나 업데이트합니다
* 복수형 객체 이름을 사용하세요(예: `CreateCompanies` 대신 `CreateCompany`)

## 속도 제한

플랫폼 안정성을 위해 API 요청에는 제한이 적용됩니다:

| 제한        | 값          |
| --------- | ---------- |
| **요청**    | 분당 100회 호출 |
| **배치 크기** | 호출당 기록 60개 |

<Tip>
처리량을 극대화하려면 배치 작업을 사용하세요 — 개별 요청 대신 단일 API 호출로 최대 60개의 기록을 처리할 수 있습니다.
</Tip>