Repository Public
1# Migrate from prompt objects23> For the complete documentation index, see [llms.txt](/llms.txt). Markdown versions of documentation pages are available by appending `.md` to the page URL.45OpenAI is deprecating reusable prompt objects in the API. Prompt creation will6 be de-emphasized beginning June 3, 2026, and `v1/prompts` is scheduled to shut7 down on November 30, 2026. See the [deprecations8 page](https://developers.openai.com/api/docs/deprecations#2026-06-03-reusable-prompts) for the current9 timeline.1011To migrate away from **Prompts** in the OpenAI API platform, move the prompt content out of the managed `prompt` object and into your application code. This gives you more control over review, testing, deployment, and versioning.1213## Before: using a Prompt Object1415Use a prompt object1617```javascript18import OpenAI from "openai";1920const client = new OpenAI();2122const response = await client.responses.create({23 prompt: {24 id: "pmpt_123",25 version: "1",26 variables: {27 customer_name: "Acme",28 issue: "billing question",29 },30 },31});32```3334```python35# Replace the illustrative IDs and URLs below with your own resource values.3637from openai import OpenAI3839client = OpenAI()40prompt_id = "pmpt_123"4142response = client.responses.create(43 prompt={44 "prompt_id": prompt_id,45 "version": "1",46 "variables": {47 "customer_name": "Acme",48 "issue": "billing question",49 },50 }51)52```5354```go55package main5657import (58 "context"59 "fmt"6061 "github.com/openai/openai-go/v3"62 "github.com/openai/openai-go/v3/responses"63)6465func main() {66 client := openai.NewClient()67 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{68 Prompt: responses.ResponsePromptParam{69 ID: "pmpt_123",70 Version: openai.String("1"),71 Variables: map[string]responses.ResponsePromptVariableUnionParam{72 "customer_name": {OfString: openai.String("Acme")},73 "issue": {OfString: openai.String("billing question")},74 },75 },76 })77 if err != nil {78 panic(err)79 }80 fmt.Println(response.OutputText())81}82```8384```java85import com.openai.client.OpenAIClient;86import com.openai.client.okhttp.OpenAIOkHttpClient;87import com.openai.core.JsonValue;88import com.openai.models.responses.ResponseCreateParams;89import com.openai.models.responses.ResponsePrompt;9091String promptId = "pmpt_123";9293ResponseCreateParams params =94 ResponseCreateParams.builder()95 .prompt(96 ResponsePrompt.builder()97 .id(promptId)98 .version("1")99 .variables(100 ResponsePrompt.Variables.builder()101 .putAdditionalProperty("customer_name", JsonValue.from("Acme"))102 .putAdditionalProperty("issue", JsonValue.from("billing question"))103 .build())104 .build())105 .build();106107client.responses().create(params).output().stream()108 .flatMap(item -> item.message().stream())109 .flatMap(message -> message.content().stream())110 .flatMap(content -> content.outputText().stream())111 .forEach(text -> System.out.println(text.text()));112```113114```ruby115require "openai"116117client = OpenAI::Client.new118119response = client.responses.create(120 prompt: {121 id: "pmpt_123",122 version: "1",123 variables: {124 customer_name: "Acme",125 issue: "billing question"126 }127 }128)129130puts(response.output_text)131```132133```bash134curl https://api.openai.com/v1/responses \135 -H "Content-Type: application/json" \136 -H "Authorization: Bearer $OPENAI_API_KEY" \137 -d '{138 "prompt": {139 "prompt_id": "pmpt_123",140 "version": "1",141 "variables": {142 "customer_name": "Acme",143 "issue": "billing question"144 }145 }146 }'147```148149150## After: inline the prompt in code151152Inline the prompt in code153154```javascript155import OpenAI from "openai";156157const client = new OpenAI();158159const response = await client.responses.create({160 model: "gpt-6-astra",161 input: [162 {163 role: "system",164 content:165 "You are a helpful support assistant. Be concise, accurate, and friendly.",166 },167 {168 role: "user",169 content:170 "Customer name: Acme. Issue: billing question. Write a response to the customer.",171 },172 ],173});174175console.log(response.output_text);176```177178```python179from openai import OpenAI180181client = OpenAI()182183response = client.responses.create(184 model="gpt-6-astra",185 input=[186 {187 "role": "system",188 "content": "You are a helpful support assistant. Be concise, accurate, and friendly.",189 },190 {191 "role": "user",192 "content": "Customer name: Acme. Issue: billing question. Write a response to the customer.",193 },194 ],195)196197print(response.output_text)198```199200```go201package main202203import (204 "context"205 "fmt"206207 "github.com/openai/openai-go/v3"208 "github.com/openai/openai-go/v3/responses"209)210211func main() {212 client := openai.NewClient()213 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{214 Model: "gpt-6-astra",215 Input: responses.ResponseNewParamsInputUnion{OfInputItemList: responses.ResponseInputParam{216 responses.ResponseInputItemParamOfMessage("You are a helpful support assistant. Be concise, accurate, and friendly.", responses.EasyInputMessageRoleSystem),217 responses.ResponseInputItemParamOfMessage("Customer name: Acme. Issue: billing question. Write a response to the customer.", responses.EasyInputMessageRoleUser),218 }},219 })220 if err != nil {221 panic(err)222 }223 fmt.Println(response.OutputText())224}225```226227```java228import com.openai.client.OpenAIClient;229import com.openai.client.okhttp.OpenAIOkHttpClient;230import com.openai.models.responses.EasyInputMessage;231import com.openai.models.responses.ResponseCreateParams;232import com.openai.models.responses.ResponseInputItem;233import java.util.List;234235ResponseCreateParams params =236 ResponseCreateParams.builder()237 .model("gpt-6-astra")238 .inputOfResponse(239 List.of(240 ResponseInputItem.ofEasyInputMessage(241 EasyInputMessage.builder()242 .role(EasyInputMessage.Role.SYSTEM)243 .content(244 "You are a helpful support assistant. Be concise, accurate, and friendly.")245 .build()),246 ResponseInputItem.ofEasyInputMessage(247 EasyInputMessage.builder()248 .role(EasyInputMessage.Role.USER)249 .content(250 "Customer name: Acme. Issue: billing question. Write a response to the customer.")251 .build())))252 .build();253254client.responses().create(params).output().stream()255 .flatMap(item -> item.message().stream())256 .flatMap(message -> message.content().stream())257 .flatMap(content -> content.outputText().stream())258 .forEach(text -> System.out.println(text.text()));259```260261```csharp262using OpenAI.Responses;263#pragma warning disable OPENAI001264265string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;266ResponsesClient client = new(key);267268ResponseResult response = await client.CreateResponseAsync(269 "gpt-6-astra",270 [271 ResponseItem.CreateSystemMessageItem(272 "You are a helpful support assistant. Be concise, accurate, and friendly."273 ),274 ResponseItem.CreateUserMessageItem(275 "Customer name: Acme. Issue: billing question. Write a response to the customer."276 ),277 ]278);279280Console.WriteLine(response.GetOutputText());281```282283```ruby284require "openai"285286client = OpenAI::Client.new287288response = client.responses.create(289 model: "gpt-6-astra",290 input: [291 {292 role: :system,293 content: "You are a helpful support assistant. Be concise, accurate, and friendly."294 },295 {296 role: :user,297 content: "Customer name: Acme. Issue: billing question. Write a response to the customer."298 }299 ]300)301302puts(response.output_text)303```304305```bash306curl https://api.openai.com/v1/responses \307 -H "Content-Type: application/json" \308 -H "Authorization: Bearer $OPENAI_API_KEY" \309 -d '{310 "model": "gpt-6-astra",311 "input": [312 {313 "role": "system",314 "content": "You are a helpful support assistant. Be concise, accurate, and friendly."315 },316 {317 "role": "user",318 "content": "Customer name: Acme. Issue: billing question. Write a response to the customer."319 }320 ]321 }'322```323324325## Use Codex to migrate326327Use the [OpenAI Developers plugin](https://developers.openai.com/learn/developers-codex-plugin) and [OpenAI Docs skill](https://github.com/openai/skills/tree/main/skills/.curated/openai-docs) to automate your migration and accelerate building with the OpenAI API.328329```text330$openai-docs update this project to store prompts in code instead of using a prompts object331```332333## What changes334335Instead of referencing a saved prompt object from an API request, store the prompt text in your codebase and pass the generated messages directly as `input` in the Responses API call.336337- **Move prompt content into source code** so prompt changes go through the same review and release process as product logic.338- **Replace prompt variables with function arguments** so dynamic values are explicit and typed in your application.339- **Pass messages through `input`** in the Responses API call instead of using the `prompt` object.340- **Move versioning to your repo** using git commits, PR review, and tests or evals.341- **Keep static content first and dynamic content later** to preserve prompt caching benefits, since cache hits depend on exact prefix matches.342343## Example344345Build prompts with a helper function346347```javascript348import OpenAI from "openai";349350const client = new OpenAI();351352function buildSupportPrompt({ customerName, issue }) {353 return [354 {355 role: "system",356 content:357 "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.",358 },359 {360 role: "user",361 content: `Customer name: ${customerName}. Issue: ${issue}. Write a response to the customer.`,362 },363 ];364}365366const response = await client.responses.create({367 model: "gpt-6-astra",368 input: buildSupportPrompt({369 customerName: "Acme",370 issue: "billing question",371 }),372});373```374375```python376from openai import OpenAI377378client = OpenAI()379380381def build_support_prompt(customer_name, issue):382 return [383 {384 "role": "system",385 "content": "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.",386 },387 {388 "role": "user",389 "content": f"Customer name: {customer_name}. Issue: {issue}. Write a response to the customer.",390 },391 ]392393394response = client.responses.create(395 model="gpt-6-astra",396 input=build_support_prompt(397 customer_name="Acme",398 issue="billing question",399 ),400)401```402403```go404package main405406import (407 "context"408 "fmt"409410 "github.com/openai/openai-go/v3"411 "github.com/openai/openai-go/v3/responses"412)413414func main() {415 client := openai.NewClient()416 response, err := client.Responses.New(context.Background(), responses.ResponseNewParams{417 Model: "gpt-6-astra",418 Input: responses.ResponseNewParamsInputUnion{OfInputItemList: buildSupportPrompt("Acme", "billing question")},419 })420 if err != nil {421 panic(err)422 }423 fmt.Println(response.OutputText())424}425426func buildSupportPrompt(customerName string, issue string) responses.ResponseInputParam {427 return responses.ResponseInputParam{428 responses.ResponseInputItemParamOfMessage("You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.", responses.EasyInputMessageRoleSystem),429 responses.ResponseInputItemParamOfMessage(fmt.Sprintf("Customer name: %s. Issue: %s. Write a response to the customer.", customerName, issue), responses.EasyInputMessageRoleUser),430 }431}432```433434```java435import com.openai.client.OpenAIClient;436import com.openai.client.okhttp.OpenAIOkHttpClient;437import com.openai.models.responses.EasyInputMessage;438import com.openai.models.responses.ResponseCreateParams;439import com.openai.models.responses.ResponseInputItem;440import java.util.List;441442private static List<ResponseInputItem> buildSupportPrompt(String customerName, String issue) {443 return List.of(444 ResponseInputItem.ofEasyInputMessage(445 EasyInputMessage.builder()446 .role(EasyInputMessage.Role.SYSTEM)447 .content(448 "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details.")449 .build()),450 ResponseInputItem.ofEasyInputMessage(451 EasyInputMessage.builder()452 .role(EasyInputMessage.Role.USER)453 .content(454 "Customer name: "455 + customerName456 + ". Issue: "457 + issue458 + ". Write a response to the customer.")459 .build()));460}461462ResponseCreateParams params =463 ResponseCreateParams.builder()464 .model("gpt-6-astra")465 .inputOfResponse(buildSupportPrompt("Acme", "billing question"))466 .build();467468client.responses().create(params).output().stream()469 .flatMap(item -> item.message().stream())470 .flatMap(message -> message.content().stream())471 .flatMap(content -> content.outputText().stream())472 .forEach(text -> System.out.println(text.text()));473```474475```csharp476using OpenAI.Responses;477#pragma warning disable OPENAI001478479string key = Environment.GetEnvironmentVariable("OPENAI_API_KEY")!;480ResponsesClient client = new(key);481482static ResponseItem[] BuildSupportPrompt(string customerName, string issue) =>483[484 ResponseItem.CreateSystemMessageItem(485 "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details."486 ),487 ResponseItem.CreateUserMessageItem(488 $"Customer name: {customerName}. Issue: {issue}. Write a response to the customer."489 ),490];491492ResponseResult response = await client.CreateResponseAsync(493 "gpt-6-astra",494 BuildSupportPrompt("Acme", "billing question")495);496Console.WriteLine(response.GetOutputText());497```498499```ruby500require "openai"501502def build_support_prompt(customer_name, issue)503 [504 {505 role: :system,506 content: "You are a helpful support assistant. Be concise, accurate, and friendly. Do not invent policy details."507 },508 {509 role: :user,510 content: "Customer name: #{customer_name}. Issue: #{issue}. Write a response to the customer."511 }512 ]513end514515client = OpenAI::Client.new516517response = client.responses.create(518 model: "gpt-6-astra",519 input: build_support_prompt("Acme", "billing question")520)521522puts(response.output_text)523```524525526## What you gain527528You get tighter engineering control: prompts live with the product code, changes go through PRs, tests and evals can run in CI, and rollout or experimentation can be managed through your own config or feature flags.529530Don't scatter prompts inline across the codebase. Create a small `prompts/` module, keep each prompt as a named builder function, and add lightweight eval fixtures so prompt changes are reviewed like product logic.