API Reference

Questions

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Create a question

questions.create(QuestionCreateParams**kwargs) -> Question

POST/v5/questions

Create a new question owned by the caller’s account.

The question is one of six types selected by the required question_type discriminator (categorical, rating, number, free_text, form, or timestamp), and each type carries its own configuration block; name and prompt are required for every type. Questions are the reusable units that are grouped into question sets and referenced by rubrics, so create them before assembling a question set. The created question is scoped to the caller’s account and records the creating identity. The question type and its configuration are set at creation time and cannot be changed afterward through the update endpoint.

ParametersExpand Collapse

question: Question

One of the following:

class QuestionCategoricalQuestionRequest: …

configuration: CategoricalQuestionConfigurationParam

choices: List[str]

Categorical answer choices (must contain at least one entry)

dropdown: Optional[bool]

Whether the question is displayed as a dropdown in the UI.

multi: Optional[bool]

Whether the question allows multiple answers.

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

question_type: Optional[Literal["categorical"]]

class QuestionRatingQuestionRequest: …

configuration: RatingQuestionConfigurationParam

max_label: str

Label shown for the maximum rating

min_label: str

Label shown for the minimum rating

steps: int

Number of discrete points on the scale (e.g., 5 for a 1–5 scale)

minimum1

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

question_type: Optional[Literal["rating"]]

class QuestionNumberQuestionRequest: …

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[NumberQuestionConfigurationParam]

max: Optional[float]

Maximum value for the number

min: Optional[float]

Minimum value for the number

question_type: Optional[Literal["number"]]

class QuestionFreeTextQuestionRequest: …

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[FreeTextQuestionConfigurationParam]

max_length: Optional[int]

Maximum characters allowed

minimum1

min_length: Optional[int]

Minimum characters required

minimum0

question_type: Optional[Literal["free_text"]]

class QuestionFormQuestionRequest: …

configuration: FormQuestionConfigurationParam

form_schema: Dict[str, object]

The JSON schema of the desired form object

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

question_type: Optional[Literal["form"]]

class QuestionTimestampQuestionRequest: …

name: str

prompt: str

user-facing question prompt

conditions: Optional[Iterable[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[TimestampQuestionConfigurationParam]

multi: Optional[bool]

Whether to allow multiple timestamps

question_type: Optional[Literal["timestamp"]]

ReturnsExpand Collapse

Question

One of the following:

class CategoricalQuestion: …

id: str

Unique identifier of the entity

configuration: CategoricalQuestionConfiguration

choices: List[str]

Categorical answer choices (must contain at least one entry)

dropdown: Optional[bool]

Whether the question is displayed as a dropdown in the UI.

multi: Optional[bool]

Whether the question allows multiple answers.

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

object: Optional[Literal["question"]]

question_type: Optional[Literal["categorical"]]

class RatingQuestion: …

id: str

Unique identifier of the entity

configuration: RatingQuestionConfiguration

max_label: str

Label shown for the maximum rating

min_label: str

Label shown for the minimum rating

steps: int

Number of discrete points on the scale (e.g., 5 for a 1–5 scale)

minimum1

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

object: Optional[Literal["question"]]

question_type: Optional[Literal["rating"]]

class NumberQuestion: …

id: str

Unique identifier of the entity

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[NumberQuestionConfiguration]

max: Optional[float]

Maximum value for the number

min: Optional[float]

Minimum value for the number

object: Optional[Literal["question"]]

question_type: Optional[Literal["number"]]

class FreeTextQuestion: …

id: str

Unique identifier of the entity

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[FreeTextQuestionConfiguration]

max_length: Optional[int]

Maximum characters allowed

minimum1

min_length: Optional[int]

Minimum characters required

minimum0

object: Optional[Literal["question"]]

question_type: Optional[Literal["free_text"]]

class FormQuestion: …

id: str

Unique identifier of the entity

configuration: FormQuestionConfiguration

form_schema: Dict[str, object]

The JSON schema of the desired form object

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

object: Optional[Literal["question"]]

question_type: Optional[Literal["form"]]

class TimestampQuestion: …

id: str

Unique identifier of the entity

created_at: datetime

ISO-timestamp when the entity was created

formatdate-time

created_by: Identity

The identity that created the entity.

id: str

type: Literal["user", "service_account"]

One of the following:

"user"

"service_account"

object: Optional[Literal["identity"]]

name: str

prompt: str

user-facing question prompt

archived_at: Optional[datetime]

ISO-timestamp when the entity was archived

formatdate-time

conditions: Optional[List[Dict[str, object]]]

Conditions for the question to be shown

configuration: Optional[TimestampQuestionConfiguration]

multi: Optional[bool]

Whether to allow multiple timestamps

object: Optional[Literal["question"]]

question_type: Optional[Literal["timestamp"]]

Create a question

Python

HTTP

TypeScript

Python

Go

import os
from scale_gp_beta import SGPClient

client = SGPClient(
    api_key=os.environ.get("SGP_API_KEY"),  # This is the default and can be omitted
)
question = client.questions.create(
    question={
        "configuration": {
            "choices": ["string"]
        },
        "name": "name",
        "prompt": "prompt",
        "question_type": "categorical",
    },
)
print(question)

200 example

{
  "id": "id",
  "configuration": {
    "choices": [
      "string"
    ],
    "dropdown": true,
    "multi": true
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "name": "name",
  "prompt": "prompt",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "conditions": [
    {
      "foo": "bar"
    }
  ],
  "object": "question",
  "question_type": "categorical"
}

Returns Examples

200 example

{
  "id": "id",
  "configuration": {
    "choices": [
      "string"
    ],
    "dropdown": true,
    "multi": true
  },
  "created_at": "2019-12-27T18:11:19.117Z",
  "created_by": {
    "id": "id",
    "type": "user",
    "object": "identity"
  },
  "name": "name",
  "prompt": "prompt",
  "archived_at": "2019-12-27T18:11:19.117Z",
  "conditions": [
    {
      "foo": "bar"
    }
  ],
  "object": "question",
  "question_type": "categorical"
}