Single-Line Text Field

A single-line text field stores short, single-line text such as names, titles, codes, or reference numbers. It is the TEXT_SINGLE value of the CustomFieldType enum. Custom fields are CustomField objects scoped to a workspace (a Workspace in the API); records are Record objects.

TEXT_SINGLE and TEXT_MULTI store and validate text the same way — the difference is the editor the app renders (a single-line input versus a multi-line textarea). Choose TEXT_SINGLE for values meant to stay on one line.

Create

Create the field with createCustomField. The workspace is taken from the blue-workspace-id header — there is no projectId argument.

mutation CreateTextSingleField {
  createCustomField(input: { name: "Client Name", type: TEXT_SINGLE }) {
    id
    name
    type
  }
}

Pass description to show help text under the field in the app:

mutation CreateDetailedTextSingleField {
  createCustomField(
    input: {
      name: "Product SKU"
      type: TEXT_SINGLE
      description: "Unique product identifier code."
    }
  ) {
    id
    name
    type
    description
  }
}

CreateCustomFieldInput

A successful call returns the created CustomField:

{
  "data": {
    "createCustomField": {
      "id": "clm4n8qwx000008l0g4oxdqn7",
      "name": "Product SKU",
      "type": "TEXT_SINGLE"
    }
  }
}

Set a value

Write text to a record with setRecordCustomField, using the text argument. The mutation returns Boolean! — true on success — so it takes no selection set.

mutation SetTextSingleValue {
  setRecordCustomField(
    input: { todoId: "todo_123", customFieldId: "field_123", text: "ORD-2024-001" }
  )
}

{ "data": { "setRecordCustomField": true } }

SetRecordCustomFieldInput

You can also set the value when creating a record. CreateRecordInput.customFields takes CreateRecordInputCustomField entries ({ customFieldId, value }), where value is the text passed as a string:

mutation CreateRecordWithSku {
  createRecord(
    input: {
      title: "Process order ORD-2024-001"
      todoListId: "list_123"
      customFields: [{ customFieldId: "field_123", value: "ORD-2024-001" }]
    }
  ) {
    id
    title
  }
}

Read a value

Record.customFields returns CustomField objects directly — there is no junction wrapper type. Read the value on each element. For TEXT_SINGLE, the value field resolves to the stored string (the same string is also on the text field).

query GetRecordSku {
  recordQueries {
    todos(filter: { companyIds: ["company_123"], todoIds: ["todo_123"] }) {
      items {
        id
        title
        customFields {
          name
          type
          text
          value
        }
      }
    }
  }
}

{
  "data": {
    "recordQueries": {
      "todos": {
        "items": [
          {
            "id": "clm4n8qwx000008l0g4oxdqn7",
            "title": "Process order ORD-2024-001",
            "customFields": [
              {
                "name": "Product SKU",
                "type": "TEXT_SINGLE",
                "text": "ORD-2024-001",
                "value": "ORD-2024-001"
              }
            ]
          }
        ]
      }
    }
  }
}

CustomField (record context)

When a CustomField is read through Record.customFields, these fields carry the record’s value:

Notes

• Text is stored verbatim through the API: no trimming, no length limit beyond the column’s storage capacity, and full Unicode support. Forms applied to the field may trim whitespace and enforce required-ness; the direct API does not.
• value is only populated when the CustomField is read in a record context (through Record.customFields). On a bare field definition fetched from the customFields query it is null.
• TEXT_SINGLE and TEXT_MULTI share storage and validation; the only difference is the editor the app renders. This parity is current behavior, not a guaranteed contract.
• To find records by text content, filter the recordQueries.todos query with the fields JSON filter rather than a dedicated text argument — there is no top-level text-search parameter on this field type.

Errors

Related

• Multi-Line Text Field — longer, free-form text.
• Email Field — email addresses.
• URL Field — links.
• Unique ID Field — auto-generated identifiers.
• Set custom field values — the setRecordCustomField reference.
• Custom Fields overview — types, access control, and operations.