---
title: Migrating from system role to developer role in OpenAi messages
url: https://calvin.my/posts/migrating-from-system-role-to-developer-role-in-openai-messages
published: 2025-05-30
updated: 2026-09-14
category: AI
tags:
- OpenAI
- API
summary: OpenAI has introduced a developer message role to replace the system role for providing instructions and context to newer reasoning models. Applications using supported models should migrate their top-level prompt from system to developer while leaving user messages unchanged. However, o1-mini accepts neither system nor developer roles and returns an unsupported-role error, so integrations must account for model-specific message-role compatibility.
---

# Migrating from system role to developer role in OpenAi messages

OpenAI has added a new role in the message input called "developer." This role replaces the existing "system" role and provides context to the thinking models. All thinking models after O1 support this new role.

Current payload:

```json
{
    "model": "o4-mini",
    "messages": [
        { "role": "system", "content": "system prompt" },
        { "role": "user", "content": "user prompt" },
    ]
}
```

New payload:

```json
{
    "model": "o4-mini",
    "messages": [
        { "role": "developer", "content": "system prompt" },
        { "role": "user", "content": "user prompt" },
    ]
}
```

* * *

This does not work for o1-mini. You will get an error trying to supply system or developer role.

```json
{
    "error": {
        "message": "Unsupported value: 'messages[0].role' does not support 'system' with this model.",
        "type": "invalid_request_error",
        "param": "messages[0].role",
        "code": "unsupported_value"
    }
}

{
    "error": {
        "message": "Unsupported value: 'messages[0].role' does not support 'developer' with this model.",
        "type": "invalid_request_error",
        "param": "messages[0].role",
        "code": "unsupported_value"
    }
}
```