openapi: 3.1.0
info:
  title: Trello REST Actions CustomFields API
  description: The Trello REST API provides programmatic access to Trello boards, lists, cards, members, labels, checklists, and other resources that make up the Trello project management platform. Developers can create, read, update, and delete Trello objects, manage team collaboration workflows, and automate task management processes. The API uses key and token based authentication and returns JSON responses for all endpoints.
  version: '1'
  contact:
    name: Atlassian Developer Support
    url: https://developer.atlassian.com/support
  termsOfService: https://www.atlassian.com/legal/cloud-terms-of-service
servers:
- url: https://api.trello.com/1
  description: Trello API v1 Production Server
security:
- apiKey: []
  apiToken: []
tags:
- name: CustomFields
  description: Operations for creating, retrieving, updating, and deleting custom field definitions and their values on boards and cards.
paths:
  /customFields:
    post:
      operationId: createCustomField
      summary: Create a Custom Field Definition
      description: Creates a new custom field definition on a board.
      tags:
      - CustomFields
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - idModel
              - modelType
              - name
              - type
              - pos
              properties:
                idModel:
                  type: string
                  description: The ID of the board to create the custom field on.
                modelType:
                  type: string
                  description: The type of model. Should be 'board'.
                  enum:
                  - board
                name:
                  type: string
                  description: The name of the custom field.
                type:
                  type: string
                  description: The type of the custom field.
                  enum:
                  - checkbox
                  - date
                  - list
                  - number
                  - text
                pos:
                  type: string
                  description: The position of the custom field.
                display_cardFront:
                  type: boolean
                  description: Whether to display the custom field on the front of cards.
                options:
                  type: array
                  description: Options for list-type custom fields.
                  items:
                    type: object
                    properties:
                      color:
                        type: string
                      value:
                        type: object
                        properties:
                          text:
                            type: string
                      pos:
                        type: integer
      responses:
        '200':
          description: Successfully created the custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
  /customFields/{id}:
    get:
      operationId: getCustomField
      summary: Get a Custom Field Definition
      description: Retrieves a custom field definition by its identifier.
      tags:
      - CustomFields
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully retrieved the custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '401':
          description: Unauthorized.
        '404':
          description: Custom field not found.
    put:
      operationId: updateCustomField
      summary: Update a Custom Field Definition
      description: Updates a custom field definition.
      tags:
      - CustomFields
      parameters:
      - $ref: '#/components/parameters/idParam'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: The new name for the custom field.
                pos:
                  type: string
                  description: The new position for the custom field.
                display/cardFront:
                  type: boolean
                  description: Whether to display on card fronts.
      responses:
        '200':
          description: Successfully updated the custom field.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CustomField'
        '401':
          description: Unauthorized.
        '404':
          description: Custom field not found.
    delete:
      operationId: deleteCustomField
      summary: Delete a Custom Field Definition
      description: Permanently deletes a custom field definition and removes its values from all cards on the board.
      tags:
      - CustomFields
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully deleted the custom field.
        '401':
          description: Unauthorized.
        '404':
          description: Custom field not found.
  /cards/{id}/customFieldItems:
    get:
      operationId: getCardCustomFieldItems
      summary: Get Custom Field Items on a Card
      description: Retrieves the custom field values set on a specific card.
      tags:
      - CustomFields
      parameters:
      - $ref: '#/components/parameters/idParam'
      responses:
        '200':
          description: Successfully retrieved custom field items.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CustomFieldItem'
        '401':
          description: Unauthorized.
        '404':
          description: Card not found.
  /cards/{idCard}/customField/{idCustomField}/item:
    put:
      operationId: updateCardCustomFieldItem
      summary: Set a Custom Field Value on a Card
      description: Sets or updates the value of a custom field on a card.
      tags:
      - CustomFields
      parameters:
      - name: idCard
        in: path
        required: true
        description: The ID of the card.
        schema:
          type: string
      - name: idCustomField
        in: path
        required: true
        description: The ID of the custom field.
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                value:
                  type: object
                  description: The value for the custom field. Structure depends on the field type.
                idValue:
                  type: string
                  description: The ID of the option value for list-type fields.
      responses:
        '200':
          description: Successfully updated the custom field value.
        '401':
          description: Unauthorized.
        '404':
          description: Card or custom field not found.
components:
  schemas:
    CustomFieldItem:
      type: object
      description: Represents a custom field value set on a specific card.
      properties:
        id:
          type: string
          description: The unique identifier for the custom field item.
        idCustomField:
          type: string
          description: The ID of the custom field definition.
        idModel:
          type: string
          description: The ID of the card.
        modelType:
          type: string
          description: The type of model (card).
        value:
          type: object
          description: The value of the custom field. Structure depends on the field type.
          properties:
            text:
              type: string
            number:
              type: string
            date:
              type: string
              format: date-time
            checked:
              type: string
        idValue:
          type: string
          description: The ID of the selected option for list-type fields.
    CustomField:
      type: object
      description: Represents a custom field definition on a board that allows structured data to be added to cards.
      properties:
        id:
          type: string
          description: The unique identifier for the custom field.
        idModel:
          type: string
          description: The ID of the model (board) the custom field belongs to.
        modelType:
          type: string
          description: The type of model (board).
        fieldGroup:
          type: string
          description: The field group identifier.
        name:
          type: string
          description: The name of the custom field.
        type:
          type: string
          description: The data type of the custom field.
          enum:
          - checkbox
          - date
          - list
          - number
          - text
        pos:
          type: number
          description: The position of the custom field.
        display:
          type: object
          description: Display settings for the custom field.
          properties:
            cardFront:
              type: boolean
              description: Whether to display on card fronts.
        options:
          type: array
          description: Options for list-type custom fields.
          items:
            type: object
            properties:
              id:
                type: string
              idCustomField:
                type: string
              value:
                type: object
                properties:
                  text:
                    type: string
              color:
                type: string
              pos:
                type: integer
  parameters:
    idParam:
      name: id
      in: path
      required: true
      description: The ID of the resource.
      schema:
        type: string
  securitySchemes:
    apiKey:
      type: apiKey
      in: query
      name: key
      description: Your Trello API key, obtained from the Power-Ups admin page at https://trello.com/power-ups/admin.
    apiToken:
      type: apiKey
      in: query
      name: token
      description: A user token that grants access to Trello resources. Obtained by authorizing via the /1/authorize route or OAuth 1.0.
externalDocs:
  description: Trello REST API Documentation
  url: https://developer.atlassian.com/cloud/trello/rest/