Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.twenty.com/llms.txt

Use this file to discover all available pages before exploring further.

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

​
개발자 우선 접근 방식

Twenty는 귀하의 데이터 모델에 맞는 API를 특별히 생성합니다:
  • 긴 ID가 필요하지 않습니다: 객체 및 필드 이름을 직접 엔드포인트에 사용합니다.
  • 표준 및 사용자 정의 객체가 동등하게 처리됩니다: 내장된 객체와 동일한 API 처리를 사용자 정의 객체에도 제공합니다.
  • 전용 엔드포인트: 각 객체와 필드에 자체 API 엔드포인트가 할당됩니다.
  • 맞춤형 문서: 작업 공간의 데이터 모델에 맞게 특별히 생성됩니다.
맞춤형 API 문서는 API 키 생성 후 설정 → API 및 웹훅에서 확인할 수 있습니다. Twenty가 사용자 지정 데이터 모델에 맞는 API를 생성하므로, 문서는 귀하의 워크스페이스에 고유합니다.

​
두 가지 API 유형

​
Core API

/rest/ 또는 /graphql/에서 접근할 수 있습니다. 실제 레코드(데이터)로 작업합니다:
  • People, Companies, Opportunities 등을 생성, 조회, 업데이트, 삭제합니다.
  • 데이터를 쿼리하고 필터링합니다
  • 데이터 기록의 관계를 관리합니다.

​
메타데이터 API

/rest/metadata/ 또는 /metadata/에서 접근할 수 있습니다. 워크스페이스와 데이터 모델 관리:
  • 객체 및 필드를 생성, 수정 또는 삭제합니다.
  • 작업 공간 설정을 구성합니다.
  • 객체 간 관계를 정의합니다

​
REST와 GraphQL

코어 및 메타데이터 API는 REST와 GraphQL 형식으로 제공됩니다:
형식사용 가능한 작업
RESTCRUD, 배치 작업, 업서트
GraphQL동일 + 배치 업서트, 한 번의 호출로 관계 쿼리
필요에 따라 선택하세요 — 두 형식 모두 동일한 데이터에 접근합니다.

​
API 엔드포인트

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

​
인증

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

​
API 키 생성

  1. 설정 → API 및 웹훅으로 이동하세요
  2. + 키 생성을 클릭하세요
  3. 구성:
    • 이름: 키를 설명하는 이름
    • 만료 날짜: 키가 만료되는 시점
  4. 저장 클릭
  5. 즉시 복사 — 키는 한 번만 표시됩니다
API 키는 민감한 데이터에 대한 액세스를 부여합니다. 신뢰할 수 없는 서비스와 공유하지 마세요. 유출되었으면 즉시 비활성화하고 새 키를 생성하세요.

​
API 키에 역할 할당

보안을 강화하려면 액세스를 제한할 특정 역할을 할당하세요:
  1. 설정 → 역할로 이동
  2. 할당할 역할을 클릭하세요
  3. 배정 탭 열기
  4. API 키에서 + API 키에 할당을 클릭하세요
  5. API 키를 선택하세요
키가 해당 역할의 권한을 상속받습니다. 자세한 내용은 권한을 참조하세요.

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