REST API & Webhooks

Relevant source files

The following files were used as context for generating this wiki page:

• packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts
• packages/twenty-shared/src/constants/DocumentationPaths.ts
• packages/twenty-front/src/locales/generated/en.ts
• packages/twenty-website/src/app/[locale]/customers/elevate-consulting/page.tsx
• packages/twenty-codex-plugin/references/develop-app/logic.md (Derived from AGENTS.md)
• packages/twenty-codex-plugin/CHANGELOG.md

The Twenty REST API and Webhooks system provides a standardized interface for external applications and internal automation to interact with workspace data. It serves as the API backbone for the go-to-market stack, enabling seamless integration between Twenty and third-party tools such as billing systems, team collaboration platforms, and custom front-end applications.

Sources: packages/twenty-website/src/app/[locale]/customers/elevate-consulting/page.tsx, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:7-10

REST API Architecture

The REST API is organized into two primary schemas: core and metadata. The core schema provides access to workspace records (e.g., Companies, People, Opportunities), while the metadata schema allows for the inspection and modification of the workspace's structure itself. The API follows Version v0.1 standards and utilizes OpenAPI 3.1.1 for documentation and schema definition.

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:7-20

Authentication

Security is enforced through Bearer Token authentication. Tokens are workspace-scoped and can be generated within the workspace settings. All requests must include the Authorization: Bearer <token> header. Passing tokens via query parameters is strictly prohibited to prevent leakage in logs or browser history.

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:24-40

Data Retrieval Operations

The API supports advanced filtering, pagination, and ordering to manage large datasets efficiently.

Feature	Description	Example Usage
Filters	Uses the filter query parameter with field-level comparators.	filter=status[eq]:"open"
Pagination	Cursor-based pagination using starting_after and ending_before.	limit=60&starting_after=cursor_id
Ordering	Sorting via order_by with directions like AscNullsFirst or DescNullsLast.	order_by=createdAt[DescNullsLast]

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:43-100

API Request Flow

This diagram illustrates the typical lifecycle of a REST API request within the Twenty ecosystem.

Webhooks and Event Integration

Webhooks enable real-time notifications by sending POST requests to external endpoints in application/json format whenever specific events occur within the workspace. This mechanism is critical for building asynchronous integrations and keeping external systems in sync with Twenty data.

Sources: packages/twenty-front/src/locales/generated/en.ts, packages/twenty-codex-plugin/CHANGELOG.md

Event Notification Workflow

When a record is modified, the system identifies associated webhooks and dispatches payloads containing the previous and new states of the entity.

Webhook Configuration

Webhooks can be configured with specific endpoints and secrets for HMAC signature computation, ensuring the integrity and authenticity of the data sent to external servers.

• Endpoint URL: The destination where POST requests are sent.
• Secret: An optional key used to compute HMAC signatures for payload verification.
• Event Filtering: Users can select which specific events (e.g., company.created, opportunity.updated) trigger the webhook.

Sources: packages/twenty-front/src/locales/generated/en.ts, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:153-157

Model Context Protocol (MCP) Integration

While the REST API provides raw data access, Twenty recommends the Model Context Protocol (MCP) for Large Language Model (LLM) agents (such as Claude or Cursor). The MCP server exposes typed tools that allow agents to interact with workspace data via header-based authentication (OAuth or API keys) without embedding tokens in URLs.

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:113-125, packages/twenty-codex-plugin/CHANGELOG.md

MCP vs REST API for LLMs

Feature	REST API	MCP Server
Primary User	Developers / External Apps	LLM Agents (Claude, Cursor)
Interface	Raw HTTP / JSON	Typed Tools
Auth for Agents	Bearer Token in Header	OAuth or API Key
Endpoint	${serverUrl}/rest	${serverUrl}/mcp

Sources: packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:113-132

Summary

The REST API and Webhooks infrastructure forms the connectivity layer of Twenty. The REST API provides comprehensive data manipulation capabilities via the core and metadata schemas, supported by robust filtering and cursor-based pagination. Webhooks extend this by providing real-time event-driven updates to external systems. Together with the MCP server, these modules allow Twenty to function as a flexible, API-first backbone for modern business operations.

Sources: packages/twenty-website/src/app/[locale]/customers/elevate-consulting/page.tsx, packages/twenty-server/src/engine/core-modules/open-api/utils/base-schema.utils.ts:7-20