# Update Batch Instructions PUT https://api.prolific.com/api/v1/data-collection/batches/{batch_id}/instructions Content-Type: application/json Updates the instructions for a task builder batch. This is a full replacement - all instructions must be included in the request. Include the `id` field for existing instructions you want to preserve. Instructions without an `id` will be created as new. Reference: https://beta-docs.prolific.com/api-reference/ai-task-builder/update-task-builder-instructions ## OpenAPI Specification ```yaml openapi: 3.1.1 info: title: Update Batch Instructions version: endpoint_aiTaskBuilder.UpdateTaskBuilderInstructions paths: /api/v1/data-collection/batches/{batch_id}/instructions: put: operationId: update-task-builder-instructions summary: Update Batch Instructions description: >- Updates the instructions for a task builder batch. This is a full replacement - all instructions must be included in the request. Include the `id` field for existing instructions you want to preserve. Instructions without an `id` will be created as new. tags: - - subpackage_aiTaskBuilder parameters: - name: batch_id in: path description: Batch ID required: true schema: type: string - name: Authorization in: header description: Header authentication of the form `undefined ` required: true schema: type: string responses: '200': description: Updated 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/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems description: The instructions for the batch. required: - instructions components: schemas: ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType: type: string enum: - value: multiple_choice - value: free_text - value: multiple_choice_with_free_text ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems: type: object properties: label: type: string description: The display text 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 ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItems: type: object properties: id: type: string format: uuid description: Include to preserve an existing instruction. type: $ref: >- #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsType 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. options: type: array items: $ref: >- #/components/schemas/ApiV1DataCollectionBatchesBatchIdInstructionsPutRequestBodyContentApplicationJsonSchemaInstructionsItemsOptionsItems 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/batch_id/instructions" payload = { "instructions": [ { "type": "multiple_choice", "description": "Choose the LLM response which is more accurate.", "id": "0192041c-470f-7336-8e3d-e03fc086a4e1", "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.", "id": "0192041c-4710-7336-8e3d-e9b6149c0797" }, { "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.put(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.prolific.com/api/v1/data-collection/batches/batch_id/instructions'; const options = { method: 'PUT', headers: {Authorization: '', 'Content-Type': 'application/json'}, body: '{"instructions":[{"type":"multiple_choice","description":"Choose the LLM response which is more accurate.","id":"0192041c-470f-7336-8e3d-e03fc086a4e1","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.","id":"0192041c-4710-7336-8e3d-e9b6149c0797"},{"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/batch_id/instructions" payload := strings.NewReader("{\n \"instructions\": [\n {\n \"type\": \"multiple_choice\",\n \"description\": \"Choose the LLM response which is more accurate.\",\n \"id\": \"0192041c-470f-7336-8e3d-e03fc086a4e1\",\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 \"id\": \"0192041c-4710-7336-8e3d-e9b6149c0797\"\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("PUT", 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/batch_id/instructions") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Put.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 \"id\": \"0192041c-470f-7336-8e3d-e03fc086a4e1\",\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 \"id\": \"0192041c-4710-7336-8e3d-e9b6149c0797\"\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.put("https://api.prolific.com/api/v1/data-collection/batches/batch_id/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 \"id\": \"0192041c-470f-7336-8e3d-e03fc086a4e1\",\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 \"id\": \"0192041c-4710-7336-8e3d-e9b6149c0797\"\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('PUT', 'https://api.prolific.com/api/v1/data-collection/batches/batch_id/instructions', [ 'body' => '{ "instructions": [ { "type": "multiple_choice", "description": "Choose the LLM response which is more accurate.", "id": "0192041c-470f-7336-8e3d-e03fc086a4e1", "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.", "id": "0192041c-4710-7336-8e3d-e9b6149c0797" }, { "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/batch_id/instructions"); var request = new RestRequest(Method.PUT); 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 \"id\": \"0192041c-470f-7336-8e3d-e03fc086a4e1\",\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 \"id\": \"0192041c-4710-7336-8e3d-e9b6149c0797\"\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.", "id": "0192041c-470f-7336-8e3d-e03fc086a4e1", "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.", "id": "0192041c-4710-7336-8e3d-e9b6149c0797" ], [ "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/batch_id/instructions")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "PUT" 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() ```