API docs by Redocly

Core System API (2026-06-23)

Download OpenAPI specification:

NYCU Software Development Club: contact@sdc.nycu.club URL: https://github.com/NYCU-SDC/core-system-api License: Apache-2.0 Terms of Service

Healthz

Check Health Status

Responses

Auth

Internal Login (Debug)

Request Body schema: application/json
required

Login request with user ID.

uid
required
string

The user ID to login as.

Responses

Request samples

Content type
application/json
{
  • "uid": "3c5fa073-7b97-43a3-bc44-ddc98f390a08"
}

Response samples

Content type
application/json
{
  • "message": "Login successful"
}

Login with OAuth Provider

path Parameters
oauthProvider
required
string (Auth.OAuthLoginProviders)
Enum: "GOOGLE" "NYCU"

The OAuth2 provider to use for login.

query Parameters
c
required
string

The callback URL of the OAuth2 login. See details

r
string

The redirect URL for login callback.

base
string

Custom base URL for OAuth callback (only used in dev mode).

Responses

Logout User

Responses

Refresh Access Token

Responses

User

Get Current User

Get the current user's information.

Responses

Response samples

Content type
application/json
{
  • "id": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "username": "john_doe",
  • "name": "John Doe",
  • "avatarUrl": "https://avatars.githubusercontent.com/u/12345678",
  • "emails": [
    ],
  • "roles": [
    ],
  • "require_onboarding": true
}

Onboard User

Onboard the current user by updating their username and other details.

Request Body schema: application/json
required
username
required
string

The user's username, can change, but must be unique across the system.

name
required
string [ 4 .. 15 ] characters ^\w+$

The user's nickname.

Responses

Request samples

Content type
application/json
{
  • "username": "jane_smith",
  • "name": "Jane Smith"
}

Response samples

Content type
application/json
{
  • "id": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "username": "john_doe",
  • "name": "John Doe",
  • "avatarUrl": "https://avatars.githubusercontent.com/u/12345678",
  • "emails": [
    ],
  • "roles": [
    ],
  • "require_onboarding": true
}

Unit

List Forms of Current User

List all forms assigned to the current user with per-user progress. Returns an empty array when the user has no forms. Requires authentication.

Responses

Response samples

Content type
application/json
[
  • {
    },
  • {
    },
  • {
    }
]

Get All Organizations

Get all organizations

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Organization

Create a new organization

Request Body schema: application/json
required
name
required
string

The name of the unit or organization

description
required
string

A brief description of the unit or organization

required
object

Metadata for the unit or organization, can include additional information like contact details, address, etc.

slug
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "NYCU SDC2",
  • "description": "陽明交大軟體開發社",
  • "slug": "nycu-sdc1",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "name": "NYCU SDC",
  • "description": "National Yang Ming Chiao Tung University Software Development Club",
  • "metadata": {
    },
  • "createdAt": "2024-01-15T08:00:00Z",
  • "updatedAt": "2024-12-20T10:30:00Z",
  • "slug": "nycu-sdc"
}

List Organizations of Current User

List all organizations of current user

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Parent-Child Relationship

Create a new parent-child relationship between units by linking them

Request Body schema: application/json
required
parentId
string <uuid> (uuid)
childId
required
string <uuid> (uuid)
orgId
required
string <uuid> (uuid)

Responses

Request samples

Content type
application/json
{
  • "parentId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "childId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "orgId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08"
}

Response samples

Content type
application/json
{
  • "parentId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "childId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "orgId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08"
}

Remove Parent-Child Relationship

Remove a parent-child relationship between units by unlinking them

path Parameters
childId
required
string <uuid> (uuid)

Responses

Get Organization

Get a specific organization by its unique identifier

path Parameters
slug
required
string

Responses

Response samples

Content type
application/json
{
  • "id": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "name": "NYCU SDC",
  • "description": "National Yang Ming Chiao Tung University Software Development Club",
  • "metadata": {
    },
  • "createdAt": "2024-01-15T08:00:00Z",
  • "updatedAt": "2024-12-20T10:30:00Z",
  • "slug": "nycu-sdc"
}

Update Organization

Update an existing organization by its unique identifier

path Parameters
slug
required
string
Request Body schema: application/json
required
name
required
string

The name of the unit or organization

description
required
string

A brief description of the unit or organization

required
object

Metadata for the unit or organization, can include additional information like contact details, address, etc.

slug
required
string

Responses

Request samples

Content type
application/json
{
  • "name": "NYCU SDC 2025",
  • "description": "Updated organization description",
  • "slug": "nycu-sdc",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "name": "NYCU SDC",
  • "description": "National Yang Ming Chiao Tung University Software Development Club",
  • "metadata": {
    },
  • "createdAt": "2024-01-15T08:00:00Z",
  • "updatedAt": "2024-12-20T10:30:00Z",
  • "slug": "nycu-sdc"
}

Delete Organization

Delete a specific organization by its unique identifier

path Parameters
slug
required
string

Responses

Create Organization Form

Create a new form under an organization.

path Parameters
slug
required
string
Request Body schema: application/json
required
title
required
string

The title of the form.

object

The form description as ProseMirror JSON, edited in Tiptap and sent by the admin interface.

previewMessage
string

(Optional) Preview text for the form. If not provided, fallback to first 25 characters of description.

deadline
string <date-time>

(Optional) Deadline for form completion.

publishTime
string <date-time>

When the form is available to be filled.

messageAfterSubmission
string

The message to show after user's submission.

object

The dressing of the form.

coverImage
string

The image path returned by the upload API.

googleSheetUrl
string

The google sheet url this form's responses will be sent to.

visibility
required
string
Enum: "PUBLIC" "PRIVATE"

The visibility setting of the form. Public forms are visible to all logged-in users. Private forms require a direct link to access.

allowEditResponse
required
boolean

Whether the user can edit their responses to the form. This is true if the form is still open and the user has already started a response, allowing them to continue editing until the deadline.

Responses

Request samples

Content type
application/json
{
  • "title": "Enter SDC Form",
  • "description": {
    },
  • "messageAfterSubmission": "Thank you for your submission!",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true
}

Response samples

Content type
application/json
{
  • "id": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "SDC 2025 Recruitment Form",
  • "description": {
    },
  • "descriptionHtml": "<p>Join us for an exciting journey in <strong>software development</strong>!</p>",
  • "previewMessage": "Join us for an exciting journey",
  • "status": "PUBLISHED",
  • "unitId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "creator": {},
  • "lastEditor": {},
  • "deadline": "2025-03-31T23:59:59Z",
  • "publishTime": "2025-02-01T00:00:00Z",
  • "messageAfterSubmission": "Thank you for your application! We'll get back to you soon.",
  • "dressing": {
    },
  • "coverImage": "https://placehold.co/1800x600/0066cc/white.webp?text=SDC+2025+Recruitment",
  • "googleSheetUrl": "https://docs.google.com/spreadsheets/d/1ABC123/edit",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z"
}

List Forms by Organization

List forms under a specific organization.

path Parameters
slug
required
string
query Parameters
status
Array of strings (Forms.FormStatus)
Default: "DRAFT,PUBLISHED"
Items Enum: "DRAFT" "PUBLISHED" "ARCHIVED"

Filter forms by status. If omitted, [DRAFT, PUBLISHED] are returned. Providing any status will override this default.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Add Organization Member

Add a member to an organization

path Parameters
slug
required
string
Request Body schema: application/json
required
email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "123@gmail.com"
}

Response samples

Content type
application/json
{
  • "orgId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "member": {}
}

List Organization Members

List all members of an organization

path Parameters
slug
required
string

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Remove Organization Member

Remove an organization-member relationship

path Parameters
slug
required
string
memberId
required
string <uuid> (uuid)

Responses

List Organization Sub-unit IDs

List all unit IDs, optionally filtered by parent organization ID

path Parameters
slug
required
string
query Parameters
parentId
string <uuid> (uuid)

The parent unit ID used to filter subunits by their parent-child relationship

Responses

Response samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

List Organization Sub-units

List all units, optionally filtered by parent organization ID

path Parameters
slug
required
string
query Parameters
parentId
string <uuid> (uuid)

The parent unit ID used to filter subunits by their parent-child relationship

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Create Unit

Create a new unit

path Parameters
slug
required
string
Request Body schema: application/json
required
name
required
string

The name of the unit or organization

description
required
string

A brief description of the unit or organization

required
object

Metadata for the unit or organization, can include additional information like contact details, address, etc.

Responses

Request samples

Content type
application/json
{
  • "name": "2025 Backend",
  • "description": "Backend course",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "name": "Backend Team",
  • "description": "Backend development team",
  • "metadata": {
    },
  • "createdAt": "2024-03-01T09:00:00Z",
  • "updatedAt": "2024-11-15T14:20:00Z"
}

Get Unit

Get a specific unit with the slug of its organization by its unique identifier

path Parameters
slug
required
string
unitId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "name": "Backend Team",
  • "description": "Backend development team",
  • "metadata": {
    },
  • "createdAt": "2024-03-01T09:00:00Z",
  • "updatedAt": "2024-11-15T14:20:00Z"
}

Update Unit

Update an existing unit or organization by its unique identifier

path Parameters
slug
required
string
unitId
required
string <uuid> (uuid)
Request Body schema: application/json
required
name
required
string

The name of the unit or organization

description
required
string

A brief description of the unit or organization

required
object

Metadata for the unit or organization, can include additional information like contact details, address, etc.

Responses

Request samples

Content type
application/json
{
  • "name": "Updated Backend Team",
  • "description": "Backend and Infrastructure team",
  • "metadata": {
    }
}

Response samples

Content type
application/json
{
  • "id": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "name": "Backend Team",
  • "description": "Backend development team",
  • "metadata": {
    },
  • "createdAt": "2024-03-01T09:00:00Z",
  • "updatedAt": "2024-11-15T14:20:00Z"
}

Delete Unit

Delete a specific unit of an organization by its unique identifier

path Parameters
slug
required
string
unitId
required
string <uuid> (uuid)

Responses

List Unit Sub-unit IDs

List all unit IDs, optionally filtered by parent unit ID

path Parameters
slug
required
string
unitId
required
string <uuid> (uuid)
query Parameters
parentId
string <uuid> (uuid)

The parent unit ID used to filter subunits by their parent-child relationship

Responses

Response samples

Content type
application/json
[
  • "497f6eca-6276-4993-bfeb-53cbbbba6f08"
]

List Unit Sub-units

List all units, optionally filtered by parent unit ID

path Parameters
slug
required
string
unitId
required
string <uuid> (uuid)
query Parameters
parentId
string <uuid> (uuid)

The parent unit ID used to filter subunits by their parent-child relationship

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Slug

Get Slug History

List the complete usage history of a given slug

path Parameters
slug
required
string

Responses

Response samples

Content type
application/json
{
  • "current": {
    },
  • "history": [
    ]
}

Get Slug Status

Get the availability of the slug.

path Parameters
slug
required
string

Responses

Response samples

Content type
application/json
{
  • "available": false,
  • "orgId": "3c5fa073-7b97-43a3-bc44-ddc98f390a08"
}

Forms

List Forms

List all existing forms.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Form Fonts

Get available fonts list for forms dressing.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Google Sheet Email

Get the Gmail address that should be added to Google Sheet permissions. This address needs to be granted access to the Google Sheet so the system can modify the form.

Responses

Response samples

Content type
application/json
{
  • "email": "core-system-bot@example.com"
}

Verify Google Sheet

Verify the Google Sheet URL and whether the system can access it.

Request Body schema: application/json
required
googleSheetUrl
required
string

The Google Sheet URL provided by user.

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "isValid": true
}

Get Form

Get a specific form by its unique identifier. Description fields are returned as ProseMirror JSON for admin editing, with rendered HTML available in descriptionHtml for frontend display.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "SDC 2025 Recruitment Form",
  • "description": {
    },
  • "descriptionHtml": "<p>Join us for an exciting journey in <strong>software development</strong>!</p>",
  • "previewMessage": "Join us for an exciting journey",
  • "status": "PUBLISHED",
  • "unitId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "creator": {},
  • "lastEditor": {},
  • "deadline": "2025-03-31T23:59:59Z",
  • "publishTime": "2025-02-01T00:00:00Z",
  • "messageAfterSubmission": "Thank you for your application! We'll get back to you soon.",
  • "dressing": {
    },
  • "coverImage": "https://placehold.co/1800x600/0066cc/white.webp?text=SDC+2025+Recruitment",
  • "googleSheetUrl": "https://docs.google.com/spreadsheets/d/1ABC123/edit",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z"
}

Update Form

Update an existing form by its unique identifier. Description fields in the request body should be sent as ProseMirror JSON from the Tiptap editor.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
title
string

The title of the form.

object

The form description as ProseMirror JSON, edited in Tiptap and sent by the admin interface.

previewMessage
string

(Optional) Preview text for the form. If not provided, fallback to first 25 characters of description.

deadline
string <date-time>

(Optional) Deadline for form completion.

publishTime
string <date-time>

When the form is available to be filled.

messageAfterSubmission
string

The message to show after user's submission.

object

The dressing of the form.

coverImage
string

The image path returned by the upload API.

googleSheetUrl
string

The google sheet url this form's responses will be sent to.

visibility
string
Enum: "PUBLIC" "PRIVATE"

The visibility setting of the form. Public forms are visible to all logged-in users. Private forms require a direct link to access.

allowEditResponse
boolean

Whether the user can edit their responses to the form. This is true if the form is still open and the user has already started a response, allowing them to continue editing until the deadline.

Responses

Request samples

Content type
application/json
{
  • "title": "Enter SDC Form",
  • "description": {
    },
  • "messageAfterSubmission": "Thank you for your submission!",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true
}

Response samples

Content type
application/json
{
  • "id": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "SDC 2025 Recruitment Form",
  • "description": {
    },
  • "descriptionHtml": "<p>Join us for an exciting journey in <strong>software development</strong>!</p>",
  • "previewMessage": "Join us for an exciting journey",
  • "status": "PUBLISHED",
  • "unitId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "creator": {},
  • "lastEditor": {},
  • "deadline": "2025-03-31T23:59:59Z",
  • "publishTime": "2025-02-01T00:00:00Z",
  • "messageAfterSubmission": "Thank you for your application! We'll get back to you soon.",
  • "dressing": {
    },
  • "coverImage": "https://placehold.co/1800x600/0066cc/white.webp?text=SDC+2025+Recruitment",
  • "googleSheetUrl": "https://docs.google.com/spreadsheets/d/1ABC123/edit",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z"
}

Delete Form

Delete an existing form by its unique identifier.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Archive Form

Archive a form. Set status to 'ARCHIVED'. Archived forms are hidden from default lists.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "SDC 2025 Recruitment Form",
  • "description": {
    },
  • "descriptionHtml": "<p>Join us for an exciting journey in <strong>software development</strong>!</p>",
  • "previewMessage": "Join us for an exciting journey",
  • "status": "PUBLISHED",
  • "unitId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "creator": {},
  • "lastEditor": {},
  • "deadline": "2025-03-31T23:59:59Z",
  • "publishTime": "2025-02-01T00:00:00Z",
  • "messageAfterSubmission": "Thank you for your application! We'll get back to you soon.",
  • "dressing": {
    },
  • "coverImage": "https://placehold.co/1800x600/0066cc/white.webp?text=SDC+2025+Recruitment",
  • "googleSheetUrl": "https://docs.google.com/spreadsheets/d/1ABC123/edit",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z"
}

Get Form Cover Image

Get the cover image binary data. Returns the image in WebP format.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Upload Form Cover Image

Upload a cover image for a form. The frontend should send images in WebP format with max-width/height: 1800px and quality 80%.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: multipart/form-data
required
coverImage
required
string <binary>

Responses

Response samples

Content type
application/json
{}

Get Form Highlight

Get the highlight question and its response statistics for a specific form. Returns 200 with questionId=null when no highlight is configured.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "questionId": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "questionTitle": "你的年級是？",
  • "displayTitle": "年級分佈統計",
  • "choices": [
    ]
}

Set Form Highlight

Set or update the highlight question for a specific form. Returns 400 if the question is not a choice-based type (singleChoice, multipleChoice, dropdown, detailedMultipleChoice).

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
questionId
required
string <uuid>

The question ID to highlight. Must be a choice-based question (singleChoice, multipleChoice, dropdown, detailedMultipleChoice).

string or null

Custom display title for the highlight. If omitted or null, the backend falls back to the question's current title.

Responses

Request samples

Content type
application/json
{
  • "questionId": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "displayTitle": "年級分佈統計"
}

Response samples

Content type
application/json
{
  • "questionId": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "questionTitle": "你的年級是？",
  • "displayTitle": "年級分佈統計",
  • "choices": [
    ]
}

Update Form Highlight

Partially update the configured highlight for a specific form. Currently supports updating displayTitle only. Send displayTitle: null to fall back to the question's current title.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
string or null

Custom display title for the highlight. Send null to fall back to the question's current title.

Responses

Request samples

Content type
application/json
{
  • "displayTitle": "Updated highlight title"
}

Response samples

Content type
application/json
{
  • "questionId": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "questionTitle": "你的年級是？",
  • "displayTitle": "年級分佈統計",
  • "choices": [
    ]
}

Clear Form Highlight

Clear the highlight question for a specific form.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Publish Form

Publish a form. Set status to 'published'.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "visibility": "PUBLIC"
}

List Sections

List all the questions of the sections in the form. Descriptions are returned as ProseMirror JSON for admin editing, with rendered HTML available in descriptionHtml for frontend form display and preview.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Update Section

Update an existing section by its unique identifier. Description fields in the request body should be sent as ProseMirror JSON from the Tiptap editor.

path Parameters
formId
required
string <uuid> (uuid)
sectionId
required
string <uuid> (uuid)
Request Body schema: application/json
required
title
string

Section title (e.g., 'Group Info').

object

The section description as ProseMirror JSON, edited in Tiptap and sent by the admin interface.

Responses

Request samples

Content type
application/json
{
  • "title": "Personal Information",
  • "description": {
    }
}

Response samples

Content type
application/json
{
  • "id": "b23f2668-c2dc-4213-88fe-eceedff46398",
  • "formId": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "Personal Information",
  • "description": {
    },
  • "descriptionHtml": "<p>Please provide your <strong>basic information</strong></p>",
  • "questions": [ ]
}

Unarchive Form

Unarchive a form. Set status to 'DRAFT'.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "title": "SDC 2025 Recruitment Form",
  • "description": {
    },
  • "descriptionHtml": "<p>Join us for an exciting journey in <strong>software development</strong>!</p>",
  • "previewMessage": "Join us for an exciting journey",
  • "status": "PUBLISHED",
  • "unitId": "d26e9c90-4747-496b-9953-7e7c4f97643f",
  • "creator": {},
  • "lastEditor": {},
  • "deadline": "2025-03-31T23:59:59Z",
  • "publishTime": "2025-02-01T00:00:00Z",
  • "messageAfterSubmission": "Thank you for your application! We'll get back to you soon.",
  • "dressing": {
    },
  • "coverImage": "https://placehold.co/1800x600/0066cc/white.webp?text=SDC+2025+Recruitment",
  • "googleSheetUrl": "https://docs.google.com/spreadsheets/d/1ABC123/edit",
  • "visibility": "PUBLIC",
  • "allowEditResponse": true,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z"
}

Get Filters

Get distinct answers of the question for filtering.

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)
questionId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "viewId": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
  • "formId": "550e8400-e29b-41d4-a716-446655440000",
  • "questionId": "74723192-bc11-412e-a576-928b76c8c9e0",
  • "answers": [
    ]
}

Create Question

Create a new question for a specific section. Description fields in the request body should be sent as ProseMirror JSON from the Tiptap editor.

The order field specifies where to insert the question within the section. The value is clamped to the valid range [1, currentCount + 1]. If the question is inserted in the middle (i.e., not appended at the end), all existing questions at or after the specified position are shifted down by one to make room for the new question.

path Parameters
sectionId
required
string <uuid> (uuid)
Request Body schema: application/json
required
required
required
boolean

Whether the question is required to answer or not.

type
required
string
Enum: "SHORT_TEXT" "LONG_TEXT" "SINGLE_CHOICE" "MULTIPLE_CHOICE" "DROPDOWN" "DETAILED_MULTIPLE_CHOICE" "DATE" "UPLOAD_FILE" "LINEAR_SCALE" "RATING" "RANKING" "OAUTH_CONNECT" "HYPERLINK"

The type of the question.

title
required
string

What is the question.

required
object

The question description as ProseMirror JSON, edited in Tiptap and sent by the admin interface.

order
required
integer <int32>

The desired position of this question within the section (1-indexed). On create, clamped to [1, currentCount + 1]; on update, clamped to [1, totalCount]. The server automatically shifts other questions to maintain a contiguous order sequence.

Array of objects (Forms.ChoiceOption)

Available choice options for single_choice, multiple_choice, dropdown, and ranking questions.

object

Available options for linear scale and rating questions.

object

Available options for file upload questions.

object

Available options for date questions.

oauthConnect
string
Enum: "GOOGLE" "GITHUB"

Available options for OAuth connect questions.

sourceId
string <uuid>

If set, choices are dynamically generated from answers to this question.

Responses

Request samples

Content type
application/json
{
  • "required": true,
  • "type": "DATE",
  • "title": "Which year did you join?",
  • "description": {
    },
  • "order": 14,
  • "date": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "sectionId": "b23f2668-c2dc-4213-88fe-eceedff46398",
  • "required": true,
  • "type": "SHORT_TEXT",
  • "title": "What's your name?",
  • "description": {
    },
  • "descriptionHtml": "<p>Please enter your <strong>full name</strong></p>",
  • "createdAt": "2025-01-20T10:00:00Z",
  • "updatedAt": "2025-02-01T15:30:00Z"
}

Update Question

Update an existing question by its unique identifier. Description fields in the request body should be sent as ProseMirror JSON from the Tiptap editor.

If the order field differs from the question's current position, the question is moved to the new position (clamped to [1, totalCount]). All questions between the old and new positions are shifted accordingly to maintain a contiguous order sequence.

path Parameters
sectionId
required
string <uuid> (uuid)
questionId
required
string <uuid> (uuid)
Request Body schema: application/json
required
required
required
boolean

Whether the question is required to answer or not.

type
required
string
Enum: "SHORT_TEXT" "LONG_TEXT" "SINGLE_CHOICE" "MULTIPLE_CHOICE" "DROPDOWN" "DETAILED_MULTIPLE_CHOICE" "DATE" "UPLOAD_FILE" "LINEAR_SCALE" "RATING" "RANKING" "OAUTH_CONNECT" "HYPERLINK"

The type of the question.

title
required
string

What is the question.

required
object

The question description as ProseMirror JSON, edited in Tiptap and sent by the admin interface.

order
required
integer <int32>

The desired position of this question within the section (1-indexed). On create, clamped to [1, currentCount + 1]; on update, clamped to [1, totalCount]. The server automatically shifts other questions to maintain a contiguous order sequence.

Array of objects (Forms.ChoiceOption)

Available choice options for single_choice, multiple_choice, dropdown, and ranking questions.

object

Available options for linear scale and rating questions.

object

Available options for file upload questions.

object

Available options for date questions.

oauthConnect
string
Enum: "GOOGLE" "GITHUB"

Available options for OAuth connect questions.

sourceId
string <uuid>

If set, choices are dynamically generated from answers to this question.

Responses

Request samples

Content type
application/json
{
  • "required": true,
  • "type": "DATE",
  • "title": "Which year did you join?",
  • "description": {
    },
  • "order": 14,
  • "date": {
    }
}

Response samples

Content type
application/json
{
  • "id": "ee894524-4bd8-4a64-8fd2-a53b39ca94cd",
  • "sectionId": "b23f2668-c2dc-4213-88fe-eceedff46398",
  • "required": true,
  • "type": "SHORT_TEXT",
  • "title": "What's your name?",
  • "description": {
    },
  • "descriptionHtml": "<p>Please enter your <strong>full name</strong></p>",
  • "createdAt": "2025-01-20T10:00:00Z",
  • "updatedAt": "2025-02-01T15:30:00Z"
}

Delete Question

Delete an existing question by its unique identifier.

After deletion, all remaining questions in the same section with a higher order value are shifted up by one to maintain a contiguous order sequence without gaps.

path Parameters
sectionId
required
string <uuid> (uuid)
questionId
required
string <uuid> (uuid)

Responses

Form Workflow

Get Workflow

Get workflow for a form

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "workflow": [ ],
  • "info": [ ]
}

Update Workflow

Update workflow for a form

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
Array
id
required
string <uuid>

Unique identifier for the node.

label
required
string

The label for the node

required
object

Arbitrary frontend-specific configuration payload for this node, stored as JSON (e.g., layout, UI settings).

object

The condition rule for the node, only for condition nodes

next
string <uuid>

Next node id for sequential flow (for start and section nodes)

nextTrue
string <uuid>

Next node id when condition is true (for condition nodes)

nextFalse
string <uuid>

Next node id when condition is false (for condition nodes)

Responses

Request samples

Content type
application/json
[
  • {
    }
]

Response samples

Content type
application/json
[
  • {
    }
]

Create Workflow Node

Create a new node for a workflow

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
type
required
string
Enum: "SECTION" "CONDITION"

Type of the node

required
object

Payload for node layout/UI settings.

Responses

Request samples

Content type
application/json
{
  • "type": "SECTION",
  • "payload": {
    }
}

Response samples

Content type
application/json
{
  • "id": "b23f2668-c2dc-4213-88fe-eceedff46398",
  • "type": "START",
  • "label": "開始表單"
}

Delete Workflow Node

Delete a node for a workflow

path Parameters
formId
required
string <uuid> (uuid)
nodeId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Responses

Create Form Response

Create a new response of a form.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "a12b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6"
}

List Form Responses

List all responses for a specific form.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "formId": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "totalCount": 150,
  • "draftCount": 30,
  • "submittedCount": 120,
  • "responses": [ ]
}

Export Form Responses

Download form responses in XLSX format.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
questionIds
required
Array of strings <uuid> (uuid) [ items <uuid > ]

The list of question IDs to include in the export.

Responses

Request samples

Content type
application/json
{
  • "questionIds": [
    ]
}

Response samples

Content type
application/json
{}

Preview Form Response Export

Get a preview of the form responses based on selected question IDs.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
questionIds
required
Array of strings <uuid> (uuid) [ items <uuid > ]

The list of question IDs to include in the export.

Responses

Request samples

Content type
application/json
{
  • "questionIds": [
    ]
}

Response samples

Content type
application/json
{
  • "headers": [
    ],
  • "rows": [
    ]
}

Get My Form Responses

Get all responses submitted by the currently logged-in user for a specific form.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "formId": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "totalCount": 150,
  • "draftCount": 30,
  • "submittedCount": 120,
  • "responses": [ ]
}

Filter And Query Form Responses

Query and filter form responses based on a list of selected question answers.

path Parameters
formId
required
string <uuid> (uuid)
Request Body schema: application/json
required
required
Array of objects (Responses.ResponseQueryFilter)

The List of questions selected.

Responses

Request samples

Content type
application/json
{
  • "filters": [
    ]
}

Response samples

Content type
application/json
{
  • "formId": "126460ed-49b2-4c69-849a-bd8904ec5d8f",
  • "responses": [
    ]
}

Get Form Response

Get the preview answer by response ID.

path Parameters
formId
required
string <uuid> (uuid)
responseId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "a12b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  • "formId": "9a843aa0-8451-4e3b-b6a0-8c0e994e9040",
  • "progress": "DRAFT",
  • "sections": [ ]
}

Delete Form Response

Delete a response and all its associated data.

path Parameters
formId
required
string <uuid> (uuid)
responseId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

OAuth Callback for Question Binding 

OAuth provider redirects here after the user authorizes (or denies) the connection.
The server exchanges the code for profile data, stores it as the answer for the question encoded in `state`, then redirects the user to `r`.

The redirect URL (`r`) will always receive the following query parameters:

| Parameter | Values | Description |
|-----------|--------|-------------|
| `status`  | `success` \| `error` | Outcome of the OAuth flow. |
| `error`   | OAuth error code (e.g. `access_denied`) | Only present when `status=error`. |

**Example redirects:**
- Success: `{r}?status=success`
- Failure: `{r}?status=error&error=access_denied`
path Parameters
provider
required
string (Auth.OAuthProviders)
Enum: "GOOGLE" "GITHUB"
query Parameters
code
string

Authorization code returned by the OAuth provider on success.

state
string

Opaque state value created during initiation; encodes responseId, questionId, and redirect URL.

error
string

Error code returned by the OAuth provider when the user denied authorization (e.g. access_denied).

Responses

Response samples

Content type
application/json
{}

Update Form Response

Update answers for the response.

path Parameters
responseId
required
string <uuid> (uuid)
Request Body schema: application/json
required
Array of Responses.StringAnswer (object) or Responses.StringArrayAnswer (object) or Responses.ScaleAnswer (object) or Responses.DateAnswer (object)

The answers to be saved. Can contain a partial subset for drafts or the full set for submission.

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ]
}

Response samples

Content type
application/json
{
  • "answers": [
    ]
}

Cancel Form Response Submission

Cancel a submitted response and revert it to draft. Only submitted responses can be canceled.

path Parameters
responseId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Get Question Response

Get a specific answer by question ID in the response.

path Parameters
responseId
required
string <uuid> (uuid)
questionId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "a12b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  • "answer": {
    }
}

Upload Question Files

Upload files as answers for a specific question in the response. This operation automatically creates or updates the answer for this question with the uploaded file URLs. The limit for each question is 10 files, and each file must be less than 10MB.

path Parameters
responseId
required
string <uuid> (uuid)
questionId
required
string <uuid> (uuid)
Request Body schema: multipart/form-data
required
files
required
Array of strings

The file(s) being uploaded.

Responses

Response samples

Content type
application/json
{
  • "files": [
    ]
}

Connect OAuth Account

Initiate OAuth flow for connecting an account to answer a question. This endpoint redirects (302) to the OAuth provider's authorization page. After authorization, the OAuth profile data (username, avatar_url) is stored as the answer and can be fetched via GET /responses/{responseId}/questions/{questionId}.

path Parameters
responseId
required
string <uuid> (uuid)

The response ID to associate this OAuth answer with.

questionId
required
string <uuid> (uuid)

The question ID being answered.

query Parameters
r
string

Optional redirect URL after OAuth completion.

Responses

Submit Form Response

Submit all the answer in the form response.

path Parameters
responseId
required
string <uuid> (uuid)
Request Body schema: application/json
required
required
Array of Responses.StringAnswer (object) or Responses.StringArrayAnswer (object) or Responses.ScaleAnswer (object) or Responses.DateAnswer (object)

The answers to be saved. Can contain a partial subset for drafts or the full set for submission.

Responses

Request samples

Content type
application/json
{
  • "answers": [
    ]
}

Response samples

Content type
application/json
{}

Views

Create Form View

Create a new view for a form with default settings. Conflict when the name is already in use.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

List Form Views

List all views for a specific form.

path Parameters
formId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Get Form View

Get a specific view by its unique identifier.

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

Update Form View

Partially update a view. Only the provided fields (name, order) will be updated. Can be used to rename, or update column visibility.

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)
Request Body schema: application/json
required
title
string

The new display title of the view.

order
integer

The new order of the current view among all views.

Responses

Request samples

Content type
application/json
{
  • "title": "React"
}

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

Delete Form View

Delete a view by its unique identifier.

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Duplicate Form View

Create a duplicate of an existing view. The new view's name defaults to the original name suffixed with '的副本'.

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

Lock Form View

Lock a view to prevent further modifications (delete).

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

Unlock Form View

Unlock a view to allow modifications (delete).

path Parameters
formId
required
string <uuid> (uuid)
viewId
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "f1a2b3c4-5d6e-7f8a-9b0c-1d2e3f4a5b6c",
  • "title": "Core System",
  • "locked": false,
  • "order": 0,
  • "createdAt": "2025-01-15T10:00:00Z",
  • "updatedAt": "2025-02-10T14:30:00Z",
  • "columns": [
    ]
}

Files

List All Files

List all files with pagination. Requires authentication.

query Parameters
limit
integer <int32>

Maximum number of files to return. Defaults to 20.

offset
integer <int32>

Number of files to skip. Defaults to 0.

Responses

Response samples

Content type
application/json
{
  • "files": [
    ],
  • "total": 1,
  • "limit": 20,
  • "offset": 0
}

List My Files

List files uploaded by the currently authenticated user.

Responses

Response samples

Content type
application/json
[
  • {
    }
]

Download File

Download a file by its ID. Returns the raw file content with appropriate Content-Type and Content-Disposition headers.

path Parameters
id
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Delete a File

Delete a file by its ID.

path Parameters
id
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{}

Get File Info

Get metadata of a file by its ID, without downloading the binary content.

path Parameters
id
required
string <uuid> (uuid)

Responses

Response samples

Content type
application/json
{
  • "id": "a12b3c4d-5e6f-7a8b-9c0d-e1f2a3b4c5d6",
  • "originalFilename": "resume.pdf",
  • "contentType": "application/pdf",
  • "size": 204800,
  • "uploadedBy": "3c5fa073-7b97-43a3-bc44-ddc98f390a08",
  • "createdAt": "2025-01-20T10:00:00Z"
}