# Create Batch Instructions POST https://api.prolific.com/api/v1/data-collection/batches/{batch_id}/instructions Content-Type: application/json Create instructions for a Task Builder batch. Reference: https://beta-docs.prolific.com/api-reference/ai-task-builder/create-task-builder-instructions ## OpenAPI Specification ```yaml openapi: 3.1.1 info: title: Create Batch Instructions version: endpoint_aiTaskBuilder.CreateTaskBuilderInstructions paths: /api/v1/data-collection/batches/{batch_id}/instructions: post: operationId: create-task-builder-instructions summary: Create Batch Instructions description: Create instructions for a Task Builder batch. tags: - - subpackage_aiTaskBuilder parameters: - name: batch_id in: path description: The unique identifier of the AI Task Builder batch required: true schema: type: string - name: Authorization in: header description: Header authentication of the form `undefined ` required: true schema: type: string responses: '201': description: Created content: application/json: schema: type: array items: $ref: '#/components/schemas/AITaskBuilderInstruction' '400': description: Error content: {} requestBody: content: application/json: schema: type: object properties: instructions: type: array items: $ref: >- #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems description: The instructions to create for the AI Task Builder batch. required: - instructions components: schemas: ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType: type: string enum: - value: multiple_choice - value: free_text - value: multiple_choice_with_free_text ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems: type: object properties: label: type: string description: The display label for the option. value: type: string description: The value associated with the option. heading: type: string description: >- The heading for the option (required for multiple_choice_with_free_text). required: - label - value ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItems: type: object properties: type: $ref: >- #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsType description: The type of instruction. description: type: string description: The question or prompt displayed to participants. helper_text: type: string description: Additional guidance text displayed below the question. placeholder_text_input: type: string description: Placeholder text displayed in the input field. answer_limit: type: integer description: >- Number of options that can be selected (required for multiple_choice and multiple_choice_with_free_text). Use 1 for single-select, -1 for unlimited. disable_dropdown: type: boolean default: false description: >- When true, always renders checkbox/radio elements instead of a dropdown select. By default, a dropdown is used when there are 5 or more options. options: type: array items: $ref: >- #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPostRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems description: >- The options (required for multiple_choice and multiple_choice_with_free_text). required: - type - description AiTaskBuilderMultipleChoiceInstructionType: type: string enum: - value: multiple_choice AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue: oneOf: - type: string - type: number format: double - type: boolean AiTaskBuilderMultipleChoiceInstructionOptionsItems: type: object properties: label: type: string description: Display text shown to participants value: $ref: >- #/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItemsValue description: Value returned in responses required: - label - value AITaskBuilderMultipleChoiceInstruction: type: object properties: id: type: string format: uuid created_at: type: string format: date-time type: $ref: '#/components/schemas/AiTaskBuilderMultipleChoiceInstructionType' batch_id: type: string created_by: type: string description: type: string description: The question or prompt displayed to participants helper_text: type: string description: Additional guidance text displayed below the question placeholder_text_input: type: string description: Placeholder text displayed in the input field answer_limit: type: integer description: >- Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to the total options. disable_dropdown: type: boolean default: false description: >- When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option count. By default, a dropdown is used when there are 5 or more options. options: type: array items: $ref: >- #/components/schemas/AiTaskBuilderMultipleChoiceInstructionOptionsItems required: - id - created_at - type - batch_id - created_by - description - answer_limit - options AiTaskBuilderFreeTextInputInstructionType: type: string enum: - value: free_text AITaskBuilderFreeTextInputInstruction: type: object properties: id: type: string format: uuid created_at: type: string format: date-time type: $ref: '#/components/schemas/AiTaskBuilderFreeTextInputInstructionType' batch_id: type: string created_by: type: string description: type: string description: The question or prompt displayed to participants helper_text: type: string description: Additional guidance text displayed below the question placeholder_text_input: type: string description: Placeholder text displayed in the input field required: - id - created_at - type - batch_id - created_by - description AiTaskBuilderMultipleChoiceWithFreeTextInstructionType: type: string enum: - value: multiple_choice_with_free_text AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue: oneOf: - type: string - type: number format: double - type: boolean AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems: type: object properties: label: type: string description: Display text shown to participants value: $ref: >- #/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItemsValue description: Value returned in responses heading: type: string description: Section heading that groups this option required: - label - value - heading AITaskBuilderMultipleChoiceWithFreeTextInstruction: type: object properties: id: type: string format: uuid created_at: type: string format: date-time type: $ref: >- #/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionType batch_id: type: string created_by: type: string description: type: string description: The question or prompt displayed to participants helper_text: type: string description: Additional guidance text displayed below the question placeholder_text_input: type: string description: Placeholder text displayed in the input field answer_limit: type: integer description: >- Number of options that can be selected. Use 1 for single-select, -1 for unlimited, or any number up to the total options. disable_dropdown: type: boolean default: false description: >- When true, always renders checkbox/radio elements instead of a dropdown select, regardless of option count. By default, a dropdown is used when there are 5 or more options. options: type: array items: $ref: >- #/components/schemas/AiTaskBuilderMultipleChoiceWithFreeTextInstructionOptionsItems required: - id - created_at - type - batch_id - created_by - description - answer_limit - options AiTaskBuilderFileUploadInstructionType: type: string enum: - value: file_upload AITaskBuilderFileUploadInstruction: type: object properties: id: type: string format: uuid created_at: type: string format: date-time type: $ref: '#/components/schemas/AiTaskBuilderFileUploadInstructionType' batch_id: type: string created_by: type: string description: type: string description: The prompt describing what to upload helper_text: type: string description: Additional guidance text displayed below the question placeholder_text_input: type: string description: Placeholder text displayed in the input field required: - id - created_at - type - batch_id - created_by - description AITaskBuilderInstruction: oneOf: - $ref: '#/components/schemas/AITaskBuilderMultipleChoiceInstruction' - $ref: '#/components/schemas/AITaskBuilderFreeTextInputInstruction' - $ref: >- #/components/schemas/AITaskBuilderMultipleChoiceWithFreeTextInstruction - $ref: '#/components/schemas/AITaskBuilderFileUploadInstruction' ``` ## SDK Code Examples ```python import requests url = "https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions" payload = { "instructions": [ { "type": "multiple_choice", "description": "Choose the LLM response which is more accurate.", "answer_limit": 1, "options": [ { "label": "Response 1", "value": "response1" }, { "label": "Response 2", "value": "response2" } ] }, { "type": "free_text", "description": "Please share the reasons for your choice.", "placeholder_text_input": "e.g. I chose this response because..." }, { "type": "multiple_choice_with_free_text", "description": "Rate each aspect and explain your reasoning.", "answer_limit": -1, "options": [ { "label": "Good", "value": "accuracy_good", "heading": "Accuracy" }, { "label": "Needs improvement", "value": "accuracy_poor", "heading": "Accuracy" } ] } ] } headers = { "Authorization": "", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions'; const options = { method: 'POST', headers: {Authorization: '', 'Content-Type': 'application/json'}, body: '{"instructions":[{"type":"multiple_choice","description":"Choose the LLM response which is more accurate.","answer_limit":1,"options":[{"label":"Response 1","value":"response1"},{"label":"Response 2","value":"response2"}]},{"type":"free_text","description":"Please share the reasons for your choice.","placeholder_text_input":"e.g. I chose this response because..."},{"type":"multiple_choice_with_free_text","description":"Rate each aspect and explain your reasoning.","answer_limit":-1,"options":[{"label":"Good","value":"accuracy_good","heading":"Accuracy"},{"label":"Needs improvement","value":"accuracy_poor","heading":"Accuracy"}]}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions" payload := strings.NewReader("{\n \"instructions\": [\n {\n \"type\": \"multiple_choice\",\n \"description\": \"Choose the LLM response which is more accurate.\",\n \"answer_limit\": 1,\n \"options\": [\n {\n \"label\": \"Response 1\",\n \"value\": \"response1\"\n },\n {\n \"label\": \"Response 2\",\n \"value\": \"response2\"\n }\n ]\n },\n {\n \"type\": \"free_text\",\n \"description\": \"Please share the reasons for your choice.\",\n \"placeholder_text_input\": \"e.g. I chose this response because...\"\n },\n {\n \"type\": \"multiple_choice_with_free_text\",\n \"description\": \"Rate each aspect and explain your reasoning.\",\n \"answer_limit\": -1,\n \"options\": [\n {\n \"label\": \"Good\",\n \"value\": \"accuracy_good\",\n \"heading\": \"Accuracy\"\n },\n {\n \"label\": \"Needs improvement\",\n \"value\": \"accuracy_poor\",\n \"heading\": \"Accuracy\"\n }\n ]\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = '' request["Content-Type"] = 'application/json' request.body = "{\n \"instructions\": [\n {\n \"type\": \"multiple_choice\",\n \"description\": \"Choose the LLM response which is more accurate.\",\n \"answer_limit\": 1,\n \"options\": [\n {\n \"label\": \"Response 1\",\n \"value\": \"response1\"\n },\n {\n \"label\": \"Response 2\",\n \"value\": \"response2\"\n }\n ]\n },\n {\n \"type\": \"free_text\",\n \"description\": \"Please share the reasons for your choice.\",\n \"placeholder_text_input\": \"e.g. I chose this response because...\"\n },\n {\n \"type\": \"multiple_choice_with_free_text\",\n \"description\": \"Rate each aspect and explain your reasoning.\",\n \"answer_limit\": -1,\n \"options\": [\n {\n \"label\": \"Good\",\n \"value\": \"accuracy_good\",\n \"heading\": \"Accuracy\"\n },\n {\n \"label\": \"Needs improvement\",\n \"value\": \"accuracy_poor\",\n \"heading\": \"Accuracy\"\n }\n ]\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java HttpResponse response = Unirest.post("https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions") .header("Authorization", "") .header("Content-Type", "application/json") .body("{\n \"instructions\": [\n {\n \"type\": \"multiple_choice\",\n \"description\": \"Choose the LLM response which is more accurate.\",\n \"answer_limit\": 1,\n \"options\": [\n {\n \"label\": \"Response 1\",\n \"value\": \"response1\"\n },\n {\n \"label\": \"Response 2\",\n \"value\": \"response2\"\n }\n ]\n },\n {\n \"type\": \"free_text\",\n \"description\": \"Please share the reasons for your choice.\",\n \"placeholder_text_input\": \"e.g. I chose this response because...\"\n },\n {\n \"type\": \"multiple_choice_with_free_text\",\n \"description\": \"Rate each aspect and explain your reasoning.\",\n \"answer_limit\": -1,\n \"options\": [\n {\n \"label\": \"Good\",\n \"value\": \"accuracy_good\",\n \"heading\": \"Accuracy\"\n },\n {\n \"label\": \"Needs improvement\",\n \"value\": \"accuracy_poor\",\n \"heading\": \"Accuracy\"\n }\n ]\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions', [ 'body' => '{ "instructions": [ { "type": "multiple_choice", "description": "Choose the LLM response which is more accurate.", "answer_limit": 1, "options": [ { "label": "Response 1", "value": "response1" }, { "label": "Response 2", "value": "response2" } ] }, { "type": "free_text", "description": "Please share the reasons for your choice.", "placeholder_text_input": "e.g. I chose this response because..." }, { "type": "multiple_choice_with_free_text", "description": "Rate each aspect and explain your reasoning.", "answer_limit": -1, "options": [ { "label": "Good", "value": "accuracy_good", "heading": "Accuracy" }, { "label": "Needs improvement", "value": "accuracy_poor", "heading": "Accuracy" } ] } ] }', 'headers' => [ 'Authorization' => '', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp var client = new RestClient("https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", ""); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"instructions\": [\n {\n \"type\": \"multiple_choice\",\n \"description\": \"Choose the LLM response which is more accurate.\",\n \"answer_limit\": 1,\n \"options\": [\n {\n \"label\": \"Response 1\",\n \"value\": \"response1\"\n },\n {\n \"label\": \"Response 2\",\n \"value\": \"response2\"\n }\n ]\n },\n {\n \"type\": \"free_text\",\n \"description\": \"Please share the reasons for your choice.\",\n \"placeholder_text_input\": \"e.g. I chose this response because...\"\n },\n {\n \"type\": \"multiple_choice_with_free_text\",\n \"description\": \"Rate each aspect and explain your reasoning.\",\n \"answer_limit\": -1,\n \"options\": [\n {\n \"label\": \"Good\",\n \"value\": \"accuracy_good\",\n \"heading\": \"Accuracy\"\n },\n {\n \"label\": \"Needs improvement\",\n \"value\": \"accuracy_poor\",\n \"heading\": \"Accuracy\"\n }\n ]\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "", "Content-Type": "application/json" ] let parameters = ["instructions": [ [ "type": "multiple_choice", "description": "Choose the LLM response which is more accurate.", "answer_limit": 1, "options": [ [ "label": "Response 1", "value": "response1" ], [ "label": "Response 2", "value": "response2" ] ] ], [ "type": "free_text", "description": "Please share the reasons for your choice.", "placeholder_text_input": "e.g. I chose this response because..." ], [ "type": "multiple_choice_with_free_text", "description": "Rate each aspect and explain your reasoning.", "answer_limit": -1, "options": [ [ "label": "Good", "value": "accuracy_good", "heading": "Accuracy" ], [ "label": "Needs improvement", "value": "accuracy_poor", "heading": "Accuracy" ] ] ] ]] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.prolific.com/api/v1/data-collection/batches/5f7b5e9a-3f3c-4b3e-8f1a-1a2b3c4d5e6f/instructions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```