API Playground

[Bonapara]

Current behavior

The API playground is located in the documentation:

• https://twenty.com/developers/rest-api/core#/
• https://twenty.com/developers/graphql/core

Desired Behavior

Warning

Ensure your implementation is pixel perfect and use our existing components

1. Separate APIs & Webhooks in two different pages

Remove the settings/developers page and create

*/settings/apis
*/settings/webhooks

Two links in the left menu :

2. Add the API Playground on the top of API page

https://www.figma.com/design/xt8O9mFeLl46C5InWwoMrN/Twenty?node-id=55437-135760&t=0PUymP3EoW0zim8v-11

Clicking on "Launch" should open a full-screen GraphQL playground OR the REST API documentation. Both will be loaded dynamically in twenty-front and will no longer be in twenty-website.

Add a storybook test for each.

I'm able to leave the full screen mode by clicking on "X".

Use the https://tabler.io/icons/icon/api icon for the Rest icon.

Pay attention to hotkeyscopes, we don't want shortcuts such as "gc" to be hijacked and affect the underlying app behind the full screen.

Pay extra attention to code quality: limit use of useEffect only when strictly impossible to avoid, don't use useMemo/callback to hide structural issues, don't create function that return JSX like renderThing, don't make a large hook that store all the logic of a single component, write intelligent tests, etc.

3. Full-Screen Playground

https://www.figma.com/design/xt8O9mFeLl46C5InWwoMrN/Twenty?node-id=56243-37941&t=0PUymP3EoW0zim8v-11

• Don't forget the border medium between the navbar and the playground
• Animate the opening of the playground by expanding the navbar (Same navbar as in the previous step, "Workspace / APIs")

4. Update the documentation

We'll deprecate the playground in the documentation (located in twenty-website) and instead redirect users to the setting page. Let's remove the Extend section and instead add an "API & Webhooks" page in Getting Started

Use these illustrations:

Please ensure the content below makes complete sense before implementation.

Twenty API & Webhooks

In this article: Discover how to use our APIs.

Overview

The Twenty API allows developers to interact programmatically with the Twenty CRM platform. Using the API, you can integrate Twenty with other systems, automate data synchronization, and build custom solutions around your customer data. The API provides endpoints to create, read, update, and delete core CRM objects (such as people and companies) as well as access metadata configuration.

API Playground: The interactive API Playground has been removed from this documentation site. You can now access the API Playground within your Twenty application’s settings. To try out API calls in real-time, log in to your Twenty app and navigate to Settings > API & Webhooks (under Developers). This will open the in-app API Playground and settings for API keys. (If you don’t see the API & Webhooks section in Settings, enable “Advanced mode” in your app settings to reveal developer options.) ➡️ [Go to API Settings](https://app.twenty.com/settings)

Authentication

Twenty’s API uses API keys for authentication. Every request to protected endpoints must include an API key in the header.

• API Keys: You can generate a new API key from your Twenty app’s API settings page. Each API key is a secret token that grants access to your CRM data, so keep it safe. If a key is compromised, revoke it from the settings and generate a new one.

• Auth Header: Once you have an API key, include it in the Authorization header of your HTTP requests. Use the Bearer token scheme. For example:

  Authorization: Bearer YOUR_API_KEY
  

  Replace YOUR_API_KEY with the key you obtained. This header must be present on all API requests. If the token is missing or invalid, the API will respond with an authentication error (HTTP 401 Unauthorized).

API Endpoints

All API endpoints are accessed via HTTPS and follow a RESTful style. The base URL for Twenty’s REST API is:

• Production (Cloud): https://api.twenty.com/rest/
• Self-Hosted Instances: If you are running Twenty on your own server, use your own domain in place of api.twenty.com (for example, https://<your-domain>/rest/).

Endpoints are grouped into two categories: Core API and Metadata API. The Core API deals with primary CRM data (e.g. people, companies, notes, tasks), while the Metadata API covers configuration data (like custom fields or object definitions). Most integrations will primarily use the Core API.

Common Resource Endpoints (Core API)

The Core API serves as a unified interface for managing core CRM entities (people, companies, notes, tasks) and their relationships, offering both REST and GraphQL interaction models. REST provides standard CRUD operations via resource-oriented endpoints, while GraphQL enables flexible, client-defined queries to fetch or modify precisely the data needed. This dual approach balances simplicity (REST) with efficiency (GraphQL) for diverse integration scenarios.

Metadata API

The Metadata API endpoints allow you to retrieve information about your Twenty CRM schema and configuration. For instance, you can fetch definitions of custom fields, object schemas, etc. These endpoints are under the base path /rest/metadata.

• Example Endpoints:
  • GET /rest/metadata/objects – List all object types and their metadata (fields, relationships).
  • GET /rest/metadata/objects/{objectName} – Get metadata for a specific object (e.g., people, companies).
  • GET /rest/metadata/picklists – Retrieve picklist (dropdown) field options defined in the CRM.

Typically, the metadata endpoints are used to understand the structure of data (for dynamic integrations or form-building) rather than to manage actual records. They are read-only in most cases. Authentication is required for these as well (use your API key).

Webhooks

In this article: Discover how to use our Webhooks.

Overview

Webhooks in Twenty complement the API by enabling real-time notifications to your own applications when certain events happen in your CRM. Instead of continuously polling the API for changes, you can set up webhooks to have Twenty push data to your system whenever specific events occur (for example, when a new record is created or an existing record is updated). This helps keep external systems in sync with Twenty instantly and efficiently.

With webhooks, Twenty will send an HTTP POST request to a URL you specify, containing details about the event. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).

Setting Up a Webhook

To create a webhook in Twenty, use the API & Webhooks settings in your Twenty app (Developer settings):

1. Navigate to Settings: In your Twenty application, go to Settings (ensure Advanced mode is enabled to see developer options).
2. Create a Webhook: Under Webhooks click on + Create webhook.
3. Enter URL: Provide the endpoint URL on your server where you want Twenty to send webhook requests. This should be a publicly accessible URL that can handle POST requests.
4. Save: Click Save to create the webhook. The new webhook will be active immediately.

You can create multiple webhooks if you need to send different events to different endpoints. Each webhook is essentially a subscription for all relevant events (at this time, Twenty sends all event types to the given URL; filtering specific event types may be configurable in the UI). If you ever need to remove a webhook, you can delete it from the same settings page (select the webhook and choose delete).

Events and Payloads

Once a webhook is set up, Twenty will send an HTTP POST request to your specified URL whenever a trigger event occurs in your CRM data. Common events that trigger webhooks include:

• Record Created: e.g. a new person is added (person.created), a new company is created (company.created), a note is created (note.created), etc.
• Record Updated: e.g. an existing person’s information is updated (person.updated), a company record is edited (company.updated), etc.
• Record Deleted: e.g. a person or company is deleted (person.deleted, company.deleted).
• Other Events: If applicable, other object events or custom triggers (for instance, if tasks or other objects are updated, similar event types would be used like task.created, note.updated, etc.).

The webhook POST request contains a JSON payload in its body. The payload will generally include at least two things: the type of event, and the data related to that event (often the record that was created/updated). For example, a webhook for a newly created person might send a payload like:

{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "[email protected]",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}

In this example:

• "event" specifies what happened (person.created).
• "data" contains the new record’s details (the same information you would get if you requested that person via the API).
• "timestamp" is when the event occurred (in UTC).

Your endpoint should be prepared to receive such JSON data via POST. Typically, you’ll parse the JSON, look at the "event" type to understand what happened, and then use the "data" accordingly (e.g., create a new contact in your system, or update an existing one).

Note: It’s important to respond with a 2xx HTTP status from your webhook endpoint to acknowledge successful receipt. If the Twenty webhook sender does not get a 2xx response, it may consider the delivery failed. (In the future, retry logic might attempt to resend failed webhooks, so always strive to return a 200 OK as quickly as possible after processing the data.)

Security and Best Practices

When using webhooks, you should secure your endpoint since it will be accepting incoming requests:

• Validate Source: Since the requests come from Twenty’s servers, you may want to verify the request truly originated from Twenty. Currently, Twenty’s webhook requests do not include a built-in signature or secret (no shared secret token was set during creation in the current version). A common practice is to use a secret token in the URL itself or as a header that only you and the Twenty system know, to validate the call. For example, when setting the webhook URL in settings, you might include a query param like ?token=YOUR_SECRET. Your endpoint can then check that token on each request.
• HTTPS: Make sure your webhook URL is using HTTPS. This ensures the data in transit is encrypted. The Twenty webhook sender will require a secure endpoint for production.
• Respond Quickly: As mentioned, respond with a 200 OK as fast as possible. If you have complex processing to do, consider queuing the work in your system after acknowledging the webhook, so that the HTTP response is not delayed. This prevents timeouts on Twenty’s side.
• Logging: It’s a good idea to log received webhook events on your server (at least during development), so you can audit or debug if you think you missed an event. This can help verify that your endpoint is receiving calls as expected.

[algora-pbc]

💎 $300 bounty • Twenty (YC S23)

Steps to solve:

1. Start working: Comment /attempt #10283 with your implementation plan
2. Submit work: Create a pull request including /claim #10283 in the PR body to claim the bounty
3. Receive payment: 100% of the bounty is received 2-5 days post-reward. Make sure you are eligible for payouts

Instructions:

1. Please re-read your code / do a self-review before marking your PR as ready for review
2. We won't review PRs until theypass linter and typecheck (npx nx lint twenty-server, npx nx lint twenty-front, npx nx typecheck twenty-front, npx nx typecheck twenty-server)
3. Check tests (npx nx storybook:serve-and-test:static twenty-front, npx nx test twenty-front, npx nx test twenty-server...)
4. Please include screens or a video/gif or your work in the PR description

Thank you for contributing to twentyhq/twenty!

Attempt	Started (GMT+0)	Solution
🟢 @Myestery	Feb 18, 2025, 10:31:28 AM	WIP
🟢 @hunxjunedo	Feb 20, 2025, 5:38:36 PM	#10369
🟢 @oliverqx		#10376

[FelixMalfait]

Note for Algora: only work on this if you are confident that you can produce high quality code on first try. No pre-assignment, first good PR merged gets the bounty.

[Myestery]

/attempt #10283

Algora profile	Completed bounties	Tech	Active attempts	Options
@Myestery	2 bounties from 2 projects	MDX, TypeScript, JavaScript & more		Cancel attempt

[hunxjunedo]

/attempt #10283

Algora profile	Completed bounties	Tech	Active attempts	Options
@hunxjunedo	20 bounties from 5 projects	TypeScript, MDX, JavaScript		Cancel attempt

[algora-pbc]

💡 @oliverqx submitted a pull request that claims the bounty. You can visit your bounty board to reward.

[algora-pbc]

🎉🎈 @oliverqx has been awarded $300! 🎈🎊

• Share on socials
• Give feedback