Passa al contenuto principale

Forms API

The forms API lets you create forms linked to boards, manage form definitions, and retrieve submissions.

Procedures​

form.list​

List all forms for a board.

Type: Query Required scope: read:board

GET /trpc/form.list?input={"boardId":"brd_abc123"}

Response:

{
  "result": {
    "data": [
      {
        "id": "frm_abc123",
        "name": "Bug Report Form",
        "boardId": "brd_abc123",
        "targetGroupId": "grp_abc123",
        "status": "active",
        "submissionCount": 142,
        "publicUrl": "https://forms.probeya.com/frm_abc123",
        "createdAt": "2026-02-01T10:00:00Z"
      }
    ]
  }
}

form.byId​

Get a form's full definition including fields and settings.

Type: Query

GET /trpc/form.byId?input={"id":"frm_abc123"}

Response:

{
  "result": {
    "data": {
      "id": "frm_abc123",
      "name": "Bug Report Form",
      "boardId": "brd_abc123",
      "targetGroupId": "grp_abc123",
      "status": "active",
      "fields": [
        {
          "fieldId": "fld_title",
          "label": "Bug Title",
          "required": true,
          "helpText": "Describe the bug in a few words"
        },
        {
          "fieldId": "fld_description",
          "label": "Steps to Reproduce",
          "required": true,
          "helpText": "List the steps to reproduce the bug"
        },
        {
          "fieldId": "fld_priority",
          "label": "Severity",
          "required": true
        }
      ],
      "settings": {
        "thankYouMessage": "Thank you for reporting this bug!",
        "allowMultiple": true,
        "requireAuth": false,
        "recaptcha": true
      },
      "branding": {
        "primaryColor": "#ef4444",
        "logo": null
      }
    }
  }
}

form.create​

Create a new form linked to a board.

Type: Mutation Required scope: write:board

POST /trpc/form.create

Input:

{
  "boardId": "brd_abc123",
  "name": "Feature Request",
  "targetGroupId": "grp_abc123",
  "fields": [
    {
      "fieldId": "fld_title",
      "label": "Feature Name",
      "required": true
    },
    {
      "fieldId": "fld_description",
      "label": "Description",
      "required": true,
      "helpText": "Describe the feature you would like"
    },
    {
      "fieldId": "fld_priority",
      "label": "How important is this?",
      "required": false
    }
  ],
  "settings": {
    "thankYouMessage": "Thanks for your suggestion!",
    "allowMultiple": true,
    "requireAuth": false
  }
}

form.update​

Update a form's definition or settings.

Type: Mutation Required scope: write:board

POST /trpc/form.update

form.delete​

Delete a form. Existing submissions (items on the board) are not affected.

Type: Mutation Required scope: write:board

POST /trpc/form.delete

Input:

{
  "id": "frm_abc123"
}

form.submit​

Submit a response to a form. This is the public endpoint used by form respondents.

Type: Mutation No authentication required (for public forms)

POST /trpc/form.submit

Input:

{
  "formId": "frm_abc123",
  "values": {
    "fld_title": "Add dark mode support",
    "fld_description": "It would be great to have a dark mode option.",
    "fld_priority": "medium"
  },
  "respondentEmail": "[email protected]"
}

form.listSubmissions​

List all submissions for a form.

Type: Query Required scope: read:board

GET /trpc/form.listSubmissions?input={"formId":"frm_abc123","cursor":null,"limit":50}