---
title: API
description: Запрашивайте и изменяйте данные CRM программно с помощью REST или GraphQL.
---

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

Twenty разработан для удобства разработчиков и предлагает мощные API, которые адаптируются к вашей пользовательской модели данных. Мы предоставляем четыре различных типа API, чтобы удовлетворить различные интеграционные потребности.

## Подход, ориентированный на разработчиков

Twenty генерирует API специально для вашей модели данных:

* **Длинные ID не требуются**: используйте названия объектов и полей прямо в конечных точках.
* **Стандартные и пользовательские объекты обрабатываются одинаково**: ваши пользовательские объекты получают такой же доступ к API, как и встроенные.
* **Выделенные конечные точки**: каждый объект и поле получают свою собственную конечную точку API.
* **Пользовательская документация**: генерируется специально для модели данных вашего рабочего пространства.

<Note>
Персонализированная документация по вашему API доступна в разделе **Настройки → API и вебхуки** после создания ключа API. Поскольку Twenty генерирует API, соответствующие вашей пользовательской модели данных, документация уникальна для вашего рабочего пространства.
</Note>

## Два типа API

### Основной API

Доступен на `/rest/` или `/graphql/`

Работайте с реальными **записями** (данными):

* Создавайте, читайте, обновляйте и удаляйте People, Companies, Opportunities и т. д.
* Запрашивайте и фильтруйте данные
* Управление отношениями записей.

### API метаданных

Доступен на `/rest/metadata/` или `/metadata/`

Управляйте своим **рабочим пространством и моделью данных**:

* Создание, изменение или удаление объектов и полей.
* Настройка параметров рабочего пространства.
* Определяйте связи между объектами

## REST против GraphQL

И Core, и Metadata API доступны в форматах REST и GraphQL:

| Формат      | Доступные операции                                                       |
| ----------- | ------------------------------------------------------------------------ |
| **REST**    | CRUD, пакетные операции, upsert-операции                                 |
| **GraphQL** | То же самое + **пакетные upsert-операции**, запросы связей за один вызов |

Выбирайте по своим потребностям — оба формата обращаются к одним и тем же данным.

## Конечные точки 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/ru/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:**

* **Пакетный upsert**: создание или обновление за один вызов
* Используйте имена объектов во множественном числе (например, `CreateCompanies` вместо `CreateCompany`)

## Лимиты скорости

Запросы к API ограничиваются для обеспечения стабильности платформы:

| Лимит             | Значение                  |
| ----------------- | ------------------------- |
| **Запросы**       | 100 запросов в минуту     |
| **Размер пакета** | 60 записей за один запрос |

<Tip>
Используйте пакетные операции, чтобы максимизировать пропускную способность — обрабатывайте до 60 записей за один запрос API вместо выполнения отдельных запросов.
</Tip>