What Are Community Custom Fields?

Custom fields let you add structured data to community posts — things like video URLs, download links, price tags, or project showcases. Instead of burying this information in post bodies, custom fields give it a dedicated, typed input that's consistent across every post in a topic.

Key concept: fields are scoped by topic. You define fields at the team level, then assign them to specific topics. A "YouTube Videos" topic might require a video_url field, while a "Templates" topic might have download_url and price fields. General Discussion? No extra fields at all.

Setting Up Custom Fields

Step 1: Define Your Fields

  1. Go to Settings > Global > Custom Fields
  2. Scroll to the Community Post Fields section
  3. Click Add Community Post Field
  4. Choose a label, field type, and whether it has a default value

Available field types:

  • Text — free-form text
  • Number — numeric values (with optional min/max)
  • Date — date picker
  • Select — dropdown with predefined options
  • Checkbox — yes/no toggle
  • URL — clickable link (renders as a hyperlink in the dashboard)

Step 2: Assign Fields to Topics

  1. Go to Settings > Team > Community
  2. Click the edit button on a topic
  3. In the Custom Fields section, check the fields you want
  4. Toggle each field as Required or Optional
  5. Click Update Topic

The same field can be required in one topic and optional in another. For example, video_url might be required in "Videos" but optional in "Showcase."

Step 3: Create Posts With Custom Fields

When agents create a post and select a topic, the relevant custom fields automatically appear in the form. Required fields must be filled before the post can be submitted.

Custom field values are displayed in the post detail sidebar with type-appropriate formatting — URLs render as clickable links, checkboxes as Yes/No, select fields show their labels.

Using Custom Fields via the API

Custom fields are available through the authenticated V1 API (secret key required). They are intentionally not included in the public community API or public community pages — this gives you private metadata space and lets headless implementations render fields however they choose.

Creating a Post with Custom Fields

POST /api/v1/teams/{teamId}/community/posts
{
  "title": "My Tutorial Video",
  "topicId": "topic-uuid",
  "customFields": {
    "field-definition-id": "https://youtube.com/watch?v=abc123"
  }
}

Reading Custom Fields

Custom fields are returned in the customFields object on post responses:

{
  "id": "post-uuid",
  "title": "My Tutorial Video",
  "customFields": {
    "field-definition-id": "https://youtube.com/watch?v=abc123"
  }
}

Topic field configuration is returned on topic responses:

{
  "id": "topic-uuid",
  "name": "Videos",
  "customFieldConfig": [
    { "fieldId": "field-def-id", "required": true }
  ]
}

CLI Usage

cstar community create \
  --title "New Video" \
  --topic-id "topic-uuid" \
  --custom-fields '{"field-id": "https://youtube.com/watch?v=abc"}'

Common Use Cases

Topic Fields Why
YouTube Videos video_url (url, required) Every video post needs a link
Templates download_url (url), is_paid (checkbox), price (number) Organize a template library
Showcase project_url (url) Let users share their work
Bug Reports browser (select), severity (select) Structured bug intake

Things to Know

  • Custom fields are internal by default. Public community pages and the widget do not display custom field values. Only the authenticated V1 API returns them.
  • Headless customers who want to render custom fields (YouTube embeds, price badges, etc.) use the V1 API and build their own UI.
  • Per-topic required overrides mean the same field can be optional in one topic and required in another.
  • Posts can only submit values for fields assigned to their topic. The server rejects any field IDs not in the topic's configuration.