Introduction

If you need to send a raw JSON document with Retrofit, the simplest approach is to pass a request body whose content type is application/json. This is different from sending form fields or query parameters. Retrofit will place the JSON text in the HTTP body exactly as the API expects, as long as you declare the endpoint correctly and use the right body type.

Use RequestBody for literal raw JSON

When you already have the full JSON string, use RequestBody as the @Body parameter.

1import okhttp3.MediaType.Companion.toMediaType
2import okhttp3.RequestBody.Companion.toRequestBody
3import retrofit2.Call
4import retrofit2.Retrofit
5import retrofit2.converter.scalars.ScalarsConverterFactory
6import retrofit2.http.Body
7import retrofit2.http.POST
8
9interface ApiService {
10    @POST("events")
11    fun postRawJson(@Body body: okhttp3.RequestBody): Call<String>
12}
13
14val json = """
15    {
16      "name": "Ada",
17      "active": true
18    }
19""".trimIndent()
20
21val mediaType = "application/json; charset=utf-8".toMediaType()
22val requestBody = json.toRequestBody(mediaType)

This is the most literal answer to "post raw whole JSON." Retrofit does not need to understand the JSON structure if you already built the string yourself.

Build Retrofit and send the request

You still need a Retrofit instance and a converter that matches the response type.

1val retrofit = Retrofit.Builder()
2    .baseUrl("https://example.com/api/")
3    .addConverterFactory(ScalarsConverterFactory.create())
4    .build()
5
6val api = retrofit.create(ApiService::class.java)
7val response = api.postRawJson(requestBody).execute()
8
9println(response.code())
10println(response.body())

This sends the raw JSON text as the request body. If your server returns JSON instead of plain text, use a JSON converter for the response side.

When a data class is better than raw JSON

Raw JSON is useful when:

• The payload is dynamic
• You are forwarding JSON from somewhere else
• The API schema is too loose for a fixed model

If the request structure is stable, a Kotlin data class or Java object is usually better because Retrofit and your JSON converter can serialize it safely.

1data class EventRequest(
2    val name: String,
3    val active: Boolean
4)

Then your interface can be:

1interface ApiService {
2    @POST("events")
3    fun postEvent(@Body body: EventRequest): Call<Unit>
4}

That is easier to maintain than hand-writing JSON strings, but it is no longer "raw whole JSON" in the literal sense.

Headers and content type still matter

Retrofit and OkHttp will set the request body bytes correctly, but the server also needs to know what those bytes represent. That is why the media type on the RequestBody matters. If you use the wrong content type, the server may reject or misinterpret the payload.

If the API also requires headers such as authentication, define them separately through interceptors or Retrofit annotations. Do not confuse headers with the JSON body itself.

Common Pitfalls

The biggest mistake is using @Field or @FormUrlEncoded when the server expects one raw JSON body. Those annotations produce a different request format entirely.

Another issue is manually building JSON strings without escaping values correctly. If the payload structure is stable, use a serializer and a data class instead of assembling strings by hand.

Developers also forget to set the JSON media type. Without application/json, some servers reject the request even though the body text looks valid.

Finally, be clear about what "raw JSON" means. If you pass a JSON string inside another object, the API may receive a string value instead of the raw document you intended.

Summary

• Use @Body RequestBody when you need to send literal raw JSON with Retrofit.
• Set the body media type to application/json.
• Use a Retrofit converter appropriate for the response type.
• Prefer a typed request model when the payload structure is stable.
• Do not mix raw JSON body requests with form-encoded annotations.