Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Ideas

Ideas are feedback or suggestions submitted by customers to your Frill account. Each idea can be assigned a Status and categorized under multiple Topics.

Idea object

Ideas have the following fields

Field
Details

idx string

A unique identifier for the idea

name string

The name of the idea

slug string

The URL slug of the idea

url string

Direct link to the idea on the public board

excerpt string

A short excerpt or summary of the idea

description string

The text description of the idea (legacy field, use content fields for structured data)

content array

Structured content as a JSON array (similar to Slate.js/ProseMirror format)

content_html string

Content rendered as HTML

content_markdown string

Content rendered as Markdown

cover_image string

Url of the image displayed as the cover on the Roadmap view

vote_count number

Number of votes this idea has received

comment_count number

Number of comments on this idea

note_count number

Number of internal notes on this idea

is_pinned boolean

Has the idea been pinned to the top

is_bug boolean

Denotes if this idea is a bug

is_archived boolean

Denotes if this idea has been archived

is_completed boolean

Denotes if this idea is considered completed / finished

show_in_roadmap boolean

Should the idea be displayed in the Roadmap view

approval_status string

The approval status of the idea: approved|needs-approval|rejected

priority_score number

The computed composite prioritization score (0 when the idea has not been prioritized — see is_prioritized)

priority_score_normalized number

The prioritization score normalized to a 0-100 scale (relative to the company's maximum possible benefit score)

priority_score_benefits number

The benefit component of the prioritization score

priority_score_costs number

The cost component of the prioritization score

is_prioritized boolean

Whether every required prioritization factor has been scored for this idea

priorities object

The idea's raw 0-10 score for each prioritization factor, keyed by the factor's company_priority idx (see Prioritization below)

created_at string

The date & time the idea was created in UTC timezone

updated_at string

The date & time the idea was last updated (UTC timezone)

author object

Author of the idea

status object

Status of the idea

topics array

Topics associated with the idea

attachments array

Files and images attached to this idea

Prioritization

Ideas carry prioritization data so you can pull priority scores into your own tools instead of only sorting by votes.

  • Each idea returns a composite priority_score (plus priority_score_normalized, priority_score_benefits and priority_score_costs), and a priorities map of the raw 0-10 score for each factor, keyed by that factor's company_priority idx.

  • The factor definitions (name, benefit/cost, weight) are returned once per response in meta.company_priorities — use each factor's idx to interpret the per-idea priorities map. The votes factor, when configured, is derived from the idea's votes and included in the map.

  • is_prioritized is true only when every required factor has been scored. Unprioritized ideas report a priority_score of 0.

  • On GET /ideas you can sort by priority_score (sortBy=priority_score) and filter by prioritization state with is_prioritized (true for fully-prioritized ideas, false for those still needing prioritization).

Endpoints

You can use the following endpoints to manage Ideas

get

Returns a list of ideas

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Query parameters
limitintegerOptional

Limits the number of items on a page

Default: 20
afterstringOptional

The after cursor - used for pagination

sortBystring · enumOptional

The field to sort by

Default: created_atPossible values:
sortstring · enumOptional

The sort direction

Default: DESCPossible values:
status_idxs[]string[]Optional

Filter to ideas in any of these statuses (OR semantics across the array). Idxs not belonging to your company are silently dropped.

Example: ["status_abcd1234"]
topic_idxs[]string[]Optional

Filter to ideas tagged with any of these topics (OR semantics). Idxs not belonging to your company are silently dropped.

board_idxstringOptional

Filter to ideas in a single board. An idx not belonging to your company is silently dropped.

is_prioritizedbooleanOptional

Filter by prioritization state. Pass false to return only unprioritized ideas (those still needing prioritization), or true for fully-prioritized ideas.

Responses
200

Successfully returned a list of ideas

application/json
get/ideas
GET /v1/ideas HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "idx": "idea_abcd1234",
      "name": "New idea",
      "slug": "new-idea",
      "url": "https://feedback.example.com/board/new-idea",
      "excerpt": "A brief summary of this idea",
      "description": "This is a new idea from a customer",
      "content": [
        {
          "type": "paragraph",
          "children": [
            {
              "text": "This is a new idea from a customer"
            }
          ]
        }
      ],
      "content_html": "<p>This is a new idea from a customer</p>",
      "content_markdown": "This is a new idea from a customer",
      "cover_image": "https://example.com/example.jpg",
      "vote_count": 1,
      "comment_count": 1,
      "note_count": 1,
      "is_pinned": true,
      "is_bug": true,
      "is_archived": true,
      "is_completed": true,
      "show_in_roadmap": true,
      "approval_status": "approved",
      "priority_score": 4200,
      "priority_score_normalized": 72,
      "priority_score_benefits": 21,
      "priority_score_costs": 0.5,
      "is_prioritized": true,
      "priorities": {
        "comp_priority_a1b2c3": 8,
        "comp_priority_d4e5f6": 6,
        "comp_priority_g7h8i9": 7,
        "comp_priority_j0k1l2": 3
      },
      "created_at": "text",
      "updated_at": "text",
      "author": {
        "idx": "user_abcd1234",
        "name": "John Smith",
        "avatar": "https://example.com/example.jpg"
      },
      "status": {
        "idx": "status_abcd1234",
        "name": "Completed",
        "color": "#6392D9"
      },
      "topics": [
        {
          "idx": "topic_abcd1234",
          "name": "New feature"
        }
      ],
      "attachments": [
        {
          "idx": "attachment_abcd1234",
          "name": "screenshot.png",
          "url": "https://cdn.frill.co/files/example.png",
          "type": "image/png",
          "created_at": "text",
          "updated_at": "text"
        }
      ]
    }
  ],
  "pagination": {
    "total": 10,
    "before": "before-cursor",
    "after": "after-cursor"
  },
  "meta": {
    "company_priorities": [
      {
        "idx": "comp_priority_a1b2c3",
        "name": "Reach",
        "type": "votes",
        "factor": "benefit",
        "weight": 1
      }
    ]
  }
}

Full-text search across idea names and descriptions. Uses Elasticsearch when available, otherwise falls back to a database query.

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Query parameters
querystringOptional

Free-text search string (preferred). Either query or term is required.

termstringOptional

Deprecated alias for query. Use query for new integrations.

limitintegerOptional

Limits the number of items on a page

Default: 20
afterstringOptional

The after cursor - used for pagination

Responses
200

Successfully returned a list of ideas

application/json
get/ideas/search
GET /v1/ideas/search HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": [
    {
      "idx": "idea_abcd1234",
      "name": "New idea",
      "slug": "new-idea",
      "url": "https://feedback.example.com/board/new-idea",
      "excerpt": "A brief summary of this idea",
      "description": "This is a new idea from a customer",
      "content": [
        {
          "type": "paragraph",
          "children": [
            {
              "text": "This is a new idea from a customer"
            }
          ]
        }
      ],
      "content_html": "<p>This is a new idea from a customer</p>",
      "content_markdown": "This is a new idea from a customer",
      "cover_image": "https://example.com/example.jpg",
      "vote_count": 1,
      "comment_count": 1,
      "note_count": 1,
      "is_pinned": true,
      "is_bug": true,
      "is_archived": true,
      "is_completed": true,
      "show_in_roadmap": true,
      "approval_status": "approved",
      "priority_score": 4200,
      "priority_score_normalized": 72,
      "priority_score_benefits": 21,
      "priority_score_costs": 0.5,
      "is_prioritized": true,
      "priorities": {
        "comp_priority_a1b2c3": 8,
        "comp_priority_d4e5f6": 6,
        "comp_priority_g7h8i9": 7,
        "comp_priority_j0k1l2": 3
      },
      "created_at": "text",
      "updated_at": "text",
      "author": {
        "idx": "user_abcd1234",
        "name": "John Smith",
        "avatar": "https://example.com/example.jpg"
      },
      "status": {
        "idx": "status_abcd1234",
        "name": "Completed",
        "color": "#6392D9"
      },
      "topics": [
        {
          "idx": "topic_abcd1234",
          "name": "New feature"
        }
      ],
      "attachments": [
        {
          "idx": "attachment_abcd1234",
          "name": "screenshot.png",
          "url": "https://cdn.frill.co/files/example.png",
          "type": "image/png",
          "created_at": "text",
          "updated_at": "text"
        }
      ]
    }
  ],
  "pagination": {
    "total": 10,
    "before": "before-cursor",
    "after": "after-cursor"
  },
  "meta": {
    "company_priorities": [
      {
        "idx": "comp_priority_a1b2c3",
        "name": "Reach",
        "type": "votes",
        "factor": "benefit",
        "weight": 1
      }
    ]
  }
}
post

Create a new idea

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Body
author_idxstringRequired

A unique identifier for the idea author

Example: follower_abcd1234
namestringRequired

The name of the idea

Example: New idea
descriptionstringRequired

The text description of the idea

Example: This is a new idea from a customer
status_idxstringOptional

A unique identifier for the idea status

Example: status_abcd1234
topic_idxsarrayOptional

array of unique identifiers for the idea topics

is_pinnedbooleanOptional

Has the idea been pinned to the top

is_archivedbooleanOptional

Denotes if this idea has been archived

show_in_roadmapbooleanOptional

Should the idea be displayed in the Roadmap view

approval_statusstring · enumOptional

The approval status of the idea. When creating an idea via REST API, you can optionally set this value.

Example: needs-approvalPossible values:
Responses
200

Return idea

application/json
post/ideas
POST /v1/ideas HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "author_idx": "follower_abcd1234",
  "name": "New idea",
  "description": "This is a new idea from a customer",
  "status_idx": "status_abcd1234",
  "topic_idxs": [],
  "is_pinned": true,
  "is_archived": true,
  "show_in_roadmap": true,
  "approval_status": "needs-approval"
}
{
  "data": {
    "idx": "idea_abcd1234",
    "name": "New idea",
    "slug": "new-idea",
    "url": "https://feedback.example.com/board/new-idea",
    "excerpt": "A brief summary of this idea",
    "description": "This is a new idea from a customer",
    "content": [
      {
        "type": "paragraph",
        "children": [
          {
            "text": "This is a new idea from a customer"
          }
        ]
      }
    ],
    "content_html": "<p>This is a new idea from a customer</p>",
    "content_markdown": "This is a new idea from a customer",
    "cover_image": "https://example.com/example.jpg",
    "vote_count": 1,
    "comment_count": 1,
    "note_count": 1,
    "is_pinned": true,
    "is_bug": true,
    "is_archived": true,
    "is_completed": true,
    "show_in_roadmap": true,
    "approval_status": "approved",
    "priority_score": 4200,
    "priority_score_normalized": 72,
    "priority_score_benefits": 21,
    "priority_score_costs": 0.5,
    "is_prioritized": true,
    "priorities": {
      "comp_priority_a1b2c3": 8,
      "comp_priority_d4e5f6": 6,
      "comp_priority_g7h8i9": 7,
      "comp_priority_j0k1l2": 3
    },
    "created_at": "text",
    "updated_at": "text",
    "author": {
      "idx": "user_abcd1234",
      "name": "John Smith",
      "avatar": "https://example.com/example.jpg"
    },
    "status": {
      "idx": "status_abcd1234",
      "name": "Completed",
      "color": "#6392D9"
    },
    "topics": [
      {
        "idx": "topic_abcd1234",
        "name": "New feature"
      }
    ],
    "attachments": [
      {
        "idx": "attachment_abcd1234",
        "name": "screenshot.png",
        "url": "https://cdn.frill.co/files/example.png",
        "type": "image/png",
        "created_at": "text",
        "updated_at": "text"
      }
    ]
  },
  "meta": {
    "company_priorities": [
      {
        "idx": "comp_priority_a1b2c3",
        "name": "Reach",
        "type": "votes",
        "factor": "benefit",
        "weight": 1
      }
    ]
  }
}
get

Get an Idea

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Path parameters
ideaIdxOrSlugstringRequired

IDX or Slug of the Idea

Responses
200

Return idea

application/json
get/ideas/{ideaIdxOrSlug}
GET /v1/ideas/{ideaIdxOrSlug} HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "data": {
    "idx": "idea_abcd1234",
    "name": "New idea",
    "slug": "new-idea",
    "url": "https://feedback.example.com/board/new-idea",
    "excerpt": "A brief summary of this idea",
    "description": "This is a new idea from a customer",
    "content": [
      {
        "type": "paragraph",
        "children": [
          {
            "text": "This is a new idea from a customer"
          }
        ]
      }
    ],
    "content_html": "<p>This is a new idea from a customer</p>",
    "content_markdown": "This is a new idea from a customer",
    "cover_image": "https://example.com/example.jpg",
    "vote_count": 1,
    "comment_count": 1,
    "note_count": 1,
    "is_pinned": true,
    "is_bug": true,
    "is_archived": true,
    "is_completed": true,
    "show_in_roadmap": true,
    "approval_status": "approved",
    "priority_score": 4200,
    "priority_score_normalized": 72,
    "priority_score_benefits": 21,
    "priority_score_costs": 0.5,
    "is_prioritized": true,
    "priorities": {
      "comp_priority_a1b2c3": 8,
      "comp_priority_d4e5f6": 6,
      "comp_priority_g7h8i9": 7,
      "comp_priority_j0k1l2": 3
    },
    "created_at": "text",
    "updated_at": "text",
    "author": {
      "idx": "user_abcd1234",
      "name": "John Smith",
      "avatar": "https://example.com/example.jpg"
    },
    "status": {
      "idx": "status_abcd1234",
      "name": "Completed",
      "color": "#6392D9"
    },
    "topics": [
      {
        "idx": "topic_abcd1234",
        "name": "New feature"
      }
    ],
    "attachments": [
      {
        "idx": "attachment_abcd1234",
        "name": "screenshot.png",
        "url": "https://cdn.frill.co/files/example.png",
        "type": "image/png",
        "created_at": "text",
        "updated_at": "text"
      }
    ]
  },
  "meta": {
    "company_priorities": [
      {
        "idx": "comp_priority_a1b2c3",
        "name": "Reach",
        "type": "votes",
        "factor": "benefit",
        "weight": 1
      }
    ]
  }
}
post

Update an Idea

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Path parameters
ideaIdxstringRequired

IDX of the Idea

Body
author_idxstringRequired

A unique identifier for the idea author

Example: follower_abcd1234
namestringRequired

The name of the idea

Example: New idea
descriptionstringRequired

The text description of the idea

Example: This is a new idea from a customer
status_idxstringOptional

A unique identifier for the idea status

Example: status_abcd1234
topic_idxsarrayOptional

array of unique identifiers for the idea topics

is_pinnedbooleanOptional

Has the idea been pinned to the top

is_archivedbooleanOptional

Denotes if this idea has been archived

show_in_roadmapbooleanOptional

Should the idea be displayed in the Roadmap view

approval_statusstring · enumOptional

The approval status of the idea. When creating an idea via REST API, you can optionally set this value.

Example: needs-approvalPossible values:
Responses
200

Return idea

application/json
post/ideas/{ideaIdx}
POST /v1/ideas/{ideaIdx} HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 244

{
  "author_idx": "follower_abcd1234",
  "name": "New idea",
  "description": "This is a new idea from a customer",
  "status_idx": "status_abcd1234",
  "topic_idxs": [],
  "is_pinned": true,
  "is_archived": true,
  "show_in_roadmap": true,
  "approval_status": "needs-approval"
}
{
  "data": {
    "idx": "idea_abcd1234",
    "name": "New idea",
    "slug": "new-idea",
    "url": "https://feedback.example.com/board/new-idea",
    "excerpt": "A brief summary of this idea",
    "description": "This is a new idea from a customer",
    "content": [
      {
        "type": "paragraph",
        "children": [
          {
            "text": "This is a new idea from a customer"
          }
        ]
      }
    ],
    "content_html": "<p>This is a new idea from a customer</p>",
    "content_markdown": "This is a new idea from a customer",
    "cover_image": "https://example.com/example.jpg",
    "vote_count": 1,
    "comment_count": 1,
    "note_count": 1,
    "is_pinned": true,
    "is_bug": true,
    "is_archived": true,
    "is_completed": true,
    "show_in_roadmap": true,
    "approval_status": "approved",
    "priority_score": 4200,
    "priority_score_normalized": 72,
    "priority_score_benefits": 21,
    "priority_score_costs": 0.5,
    "is_prioritized": true,
    "priorities": {
      "comp_priority_a1b2c3": 8,
      "comp_priority_d4e5f6": 6,
      "comp_priority_g7h8i9": 7,
      "comp_priority_j0k1l2": 3
    },
    "created_at": "text",
    "updated_at": "text",
    "author": {
      "idx": "user_abcd1234",
      "name": "John Smith",
      "avatar": "https://example.com/example.jpg"
    },
    "status": {
      "idx": "status_abcd1234",
      "name": "Completed",
      "color": "#6392D9"
    },
    "topics": [
      {
        "idx": "topic_abcd1234",
        "name": "New feature"
      }
    ],
    "attachments": [
      {
        "idx": "attachment_abcd1234",
        "name": "screenshot.png",
        "url": "https://cdn.frill.co/files/example.png",
        "type": "image/png",
        "created_at": "text",
        "updated_at": "text"
      }
    ]
  },
  "meta": {
    "company_priorities": [
      {
        "idx": "comp_priority_a1b2c3",
        "name": "Reach",
        "type": "votes",
        "factor": "benefit",
        "weight": 1
      }
    ]
  }
}
delete

Delete an Idea

Authorizations
AuthorizationstringRequired

API key in Authorization header with Bearer prefix (recommended)

Path parameters
ideaIdxstringRequired

IDX of the Idea

Responses
200

Request was successful

application/json
successbooleanOptional
messagestringOptionalExample: Request was successful
delete/ideas/{ideaIdx}
DELETE /v1/ideas/{ideaIdx} HTTP/1.1
Host: api.frill.co
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "message": "Request was successful"
}
PreviousAnnouncement Categories
NextComments

Last updated