Migrate from prompt objects

To 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.

Before: using a Prompt Object

Use a prompt object

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  prompt: {
    prompt_id: "pmpt_123",
    version: "1",
    variables: {
      customer_name: "Acme",
      issue: "billing question",
    },
  },
});

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    prompt={
        "prompt_id": "pmpt_123",
        "version": "1",
        "variables": {
            "customer_name": "Acme",
            "issue": "billing question",
        },
    }
)

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
    "prompt": {
      "prompt_id": "pmpt_123",
      "version": "1",
      "variables": {
        "customer_name": "Acme",
        "issue": "billing question"
      }
    }
  }'

After: inline the prompt in code

Inline the prompt in code

import OpenAI from "openai";

const client = new OpenAI();

const response = await client.responses.create({
  model: "gpt-5.1",
  input: [
    {
      role: "system",
      content:
        "You are a helpful support assistant. Be concise, accurate, and friendly.",
    },
    {
      role: "user",
      content: \`
Customer name: Acme
Issue: billing question

Write a response to the customer.
      \`.trim(),
    },
  ],
});

console.log(response.output_text);

from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.1",
    input=[
        {
            "role": "system",
            "content": "You are a helpful support assistant. Be concise, accurate, and friendly.",
        },
        {
            "role": "user",
            "content": """
Customer name: Acme
Issue: billing question

Write a response to the customer.
            """.strip(),
        },
    ],
)

print(response.output_text)

curl https://api.openai.com/v1/responses \\
  -H "Content-Type: application/json" \\
  -H "Authorization: Bearer $OPENAI_API_KEY" \\
  -d '{
    "model": "gpt-5.1",
    "input": [
      {
        "role": "system",
        "content": "You are a helpful support assistant. Be concise, accurate, and friendly."
      },
      {
        "role": "user",
        "content": "Customer name: Acme\\nIssue: billing question\\n\\nWrite a response to the customer."
      }
    ]
  }'

Use Codex to migrate

Use the OpenAI Developers plugin and OpenAI Docs skill to automate your migration and accelerate building with the OpenAI API.

$openai-docs update this project to store prompts in code instead of using a prompts object

What changes

Instead 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.

Move prompt content into source code so prompt changes go through the same review and release process as product logic.
Replace prompt variables with function arguments so dynamic values are explicit and typed in your application.
Pass messages through input in the Responses API call instead of using the prompt object.
Move versioning to your repo using git commits, PR review, and tests or evals.
Keep static content first and dynamic content later to preserve prompt caching benefits, since cache hits depend on exact prefix matches.

Example

Build prompts with a helper function

import OpenAI from "openai";

const client = new OpenAI();

function buildSupportPrompt({ customerName, issue }) {
  return [
    {
      role: "system",
      content: \`
You are a helpful support assistant.
Be concise, accurate, and friendly.
Do not invent policy details.
      \`.trim(),
    },
    {
      role: "user",
      content: \`
Customer name: \${customerName}
Issue: \${issue}

Write a response to the customer.
      \`.trim(),
    },
  ];
}

const response = await client.responses.create({
  model: "gpt-5.1",
  input: buildSupportPrompt({
    customerName: "Acme",
    issue: "billing question",
  }),
});

from openai import OpenAI

client = OpenAI()

def build_support_prompt(customer_name, issue):
    return [
        {
            "role": "system",
            "content": """
You are a helpful support assistant.
Be concise, accurate, and friendly.
Do not invent policy details.
            """.strip(),
        },
        {
            "role": "user",
            "content": f"""
Customer name: {customer_name}
Issue: {issue}

Write a response to the customer.
            """.strip(),
        },
    ]

response = client.responses.create(
    model="gpt-5.1",
    input=build_support_prompt(
        customer_name="Acme",
        issue="billing question",
    ),
)

What you gain

You 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.

Don'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.

guides/prompting/migrate-from-prompt-object.md +237 −0 created

1# Migrate from prompt objects

3To 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.

5## Before: using a Prompt Object

7Use a prompt object

9```javascript

10import OpenAI from "openai";

12const client = new OpenAI();

14const response = await client.responses.create({

15 prompt: {

16 prompt_id: "pmpt_123",

17 version: "1",

18 variables: {

19 customer_name: "Acme",

20 issue: "billing question",

21 },

22 },

23});

24```

26```python

27from openai import OpenAI

29client = OpenAI()

31response = client.responses.create(

32 prompt={

33 "prompt_id": "pmpt_123",

34 "version": "1",

35 "variables": {

36 "customer_name": "Acme",

37 "issue": "billing question",

38 },

39 }

40)

41```

43```bash

44curl https://api.openai.com/v1/responses \\

45 -H "Content-Type: application/json" \\

46 -H "Authorization: Bearer $OPENAI_API_KEY" \\

47 -d '{

48 "prompt": {

49 "prompt_id": "pmpt_123",

50 "version": "1",

51 "variables": {

52 "customer_name": "Acme",

53 "issue": "billing question"

54 }

55 }

56 }'

57```

60## After: inline the prompt in code

62Inline the prompt in code

64```javascript

65import OpenAI from "openai";

67const client = new OpenAI();

69const response = await client.responses.create({

70 model: "gpt-5.1",

71 input: [

72 {

73 role: "system",

74 content:

75 "You are a helpful support assistant. Be concise, accurate, and friendly.",

76 },

77 {

78 role: "user",

79 content: \`

80Customer name: Acme

81Issue: billing question

83Write a response to the customer.

84 \`.trim(),

85 },

86 ],

87});

89console.log(response.output_text);

90```

92```python

93from openai import OpenAI

95client = OpenAI()

97response = client.responses.create(

98 model="gpt-5.1",

99 input=[

100 {

101 "role": "system",

102 "content": "You are a helpful support assistant. Be concise, accurate, and friendly.",

103 },

104 {

105 "role": "user",

106 "content": """

107Customer name: Acme

108Issue: billing question

109

110Write a response to the customer.

111 """.strip(),

112 },

113 ],

114)

115

116print(response.output_text)

117```

118

119```bash

120curl https://api.openai.com/v1/responses \\

121 -H "Content-Type: application/json" \\

122 -H "Authorization: Bearer $OPENAI_API_KEY" \\

123 -d '{

124 "model": "gpt-5.1",

125 "input": [

126 {

127 "role": "system",

128 "content": "You are a helpful support assistant. Be concise, accurate, and friendly."

129 },

130 {

131 "role": "user",

132 "content": "Customer name: Acme\\nIssue: billing question\\n\\nWrite a response to the customer."

133 }

134 ]

135 }'

136```

137

138

139## Use Codex to migrate

140

141Use 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.

142

143```text

144$openai-docs update this project to store prompts in code instead of using a prompts object

145```

146

147## What changes

148

149Instead 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.

150

151- **Move prompt content into source code** so prompt changes go through the same review and release process as product logic.

152- **Replace prompt variables with function arguments** so dynamic values are explicit and typed in your application.

153- **Pass messages through `input`** in the Responses API call instead of using the `prompt` object.

154- **Move versioning to your repo** using git commits, PR review, and tests or evals.

155- **Keep static content first and dynamic content later** to preserve prompt caching benefits, since cache hits depend on exact prefix matches.

156

157## Example

158

159Build prompts with a helper function

160

161```javascript

162import OpenAI from "openai";

163

164const client = new OpenAI();

165

166function buildSupportPrompt({ customerName, issue }) {

167 return [

168 {

169 role: "system",

170 content: \`

171You are a helpful support assistant.

172Be concise, accurate, and friendly.

173Do not invent policy details.

174 \`.trim(),

175 },

176 {

177 role: "user",

178 content: \`

179Customer name: \${customerName}

180Issue: \${issue}

181

182Write a response to the customer.

183 \`.trim(),

184 },

185 ];

186}

187

188const response = await client.responses.create({

189 model: "gpt-5.1",

190 input: buildSupportPrompt({

191 customerName: "Acme",

192 issue: "billing question",

193 }),

194});

195```

196

197```python

198from openai import OpenAI

199

200client = OpenAI()

201

202def build_support_prompt(customer_name, issue):

203 return [

204 {

205 "role": "system",

206 "content": """

207You are a helpful support assistant.

208Be concise, accurate, and friendly.

209Do not invent policy details.

210 """.strip(),

211 },

212 {

213 "role": "user",

214 "content": f"""

215Customer name: {customer_name}

216Issue: {issue}

217

218Write a response to the customer.

219 """.strip(),

220 },

221 ]

222

223response = client.responses.create(

224 model="gpt-5.1",

225 input=build_support_prompt(

226 customer_name="Acme",

227 issue="billing question",

228 ),

229)

230```

231

232

233## What you gain

234

235You 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.

236

237Don'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.