openapi: 3.0.1
info:
  title: Twenty CRM Companies Metadata - Fields API
  description: 'REST specification for Twenty, the open-source CRM. Twenty auto-generates a REST API (and a parallel GraphQL API) from your workspace data model. This document covers the Core API (CRUD over records such as People, Companies, Opportunities, Notes, and Tasks) and the Metadata API (schema management for objects and fields). Endpoints are served from a per-workspace base URL: https://api.twenty.com on Twenty Cloud, or https://{your-domain} when self-hosted. The Core API lives under /rest and the Metadata API under /rest/metadata. All requests are authenticated with a Bearer API key created in Settings -> API & Webhooks.'
  termsOfService: https://twenty.com/legal/tos
  contact:
    name: Twenty
    url: https://twenty.com/
  license:
    name: AGPL-3.0
    url: https://github.com/twentyhq/twenty/blob/main/LICENSE
  version: '0.40'
servers:
- url: https://api.twenty.com
  description: Twenty Cloud
- url: https://{domain}
  description: Self-hosted workspace
  variables:
    domain:
      default: your-domain.com
      description: Your self-hosted Twenty instance host.
security:
- bearerAuth: []
tags:
- name: Metadata - Fields
  description: Metadata API management of field definitions.
paths:
  /rest/metadata/fields:
    get:
      operationId: listFieldMetadata
      tags:
      - Metadata - Fields
      summary: List field metadata
      responses:
        '200':
          description: A list of field definitions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMetadataListResponse'
    post:
      operationId: createFieldMetadata
      tags:
      - Metadata - Fields
      summary: Create a field
      description: Adds a field to an object. Use a relation field type to define a relation between objects.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldMetadataInput'
      responses:
        '201':
          description: The created field definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMetadataResponse'
  /rest/metadata/fields/{id}:
    parameters:
    - $ref: '#/components/parameters/RecordId'
    get:
      operationId: getFieldMetadata
      tags:
      - Metadata - Fields
      summary: Get a field definition
      responses:
        '200':
          description: The requested field definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMetadataResponse'
        '404':
          $ref: '#/components/responses/NotFound'
    patch:
      operationId: updateFieldMetadata
      tags:
      - Metadata - Fields
      summary: Update a field definition
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FieldMetadataInput'
      responses:
        '200':
          description: The updated field definition.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FieldMetadataResponse'
    delete:
      operationId: deleteFieldMetadata
      tags:
      - Metadata - Fields
      summary: Delete a field definition
      responses:
        '200':
          $ref: '#/components/responses/Deleted'
components:
  schemas:
    PageInfo:
      type: object
      properties:
        hasNextPage:
          type: boolean
        startCursor:
          type: string
        endCursor:
          type: string
    FieldMetadata:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        label:
          type: string
        type:
          type: string
          enum:
          - TEXT
          - NUMBER
          - BOOLEAN
          - DATE_TIME
          - SELECT
          - MULTI_SELECT
          - CURRENCY
          - EMAILS
          - PHONES
          - LINKS
          - RELATION
          - RATING
          - UUID
        objectMetadataId:
          type: string
          format: uuid
        isCustom:
          type: boolean
        isNullable:
          type: boolean
    FieldMetadataResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            field:
              $ref: '#/components/schemas/FieldMetadata'
    Error:
      type: object
      properties:
        statusCode:
          type: integer
        messages:
          type: array
          items:
            type: string
        error:
          type: string
    FieldMetadataInput:
      type: object
      required:
      - name
      - label
      - type
      - objectMetadataId
      properties:
        name:
          type: string
        label:
          type: string
        type:
          type: string
        objectMetadataId:
          type: string
          format: uuid
        description:
          type: string
        icon:
          type: string
        relationCreationPayload:
          type: object
          description: Used when type is RELATION to define the related object and relation kind.
    FieldMetadataListResponse:
      type: object
      properties:
        data:
          type: object
          properties:
            fields:
              type: array
              items:
                $ref: '#/components/schemas/FieldMetadata'
        pageInfo:
          $ref: '#/components/schemas/PageInfo'
  parameters:
    RecordId:
      name: id
      in: path
      required: true
      description: The UUID of the record.
      schema:
        type: string
        format: uuid
  responses:
    NotFound:
      description: The record was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Deleted:
      description: The record was deleted.
      content:
        application/json:
          schema:
            type: object
            properties:
              data:
                type: object
                properties:
                  deletePerson:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: 'API key created in Settings -> API & Webhooks, sent as `Authorization: Bearer <API_KEY>`.'