> For the complete documentation index, see [llms.txt](https://docs.plenit.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plenit.com/docs-en/reference/getting-started/beginners-guide-payload-headers-and-example-request.md).

# Beginner's Guide: Payload, Headers, and a Practical Example

## What Is a Payload and How Is It Used in an API Request?

When you send a request to an API, you sometimes need to include information so the API knows exactly what you want it to do. This information is sent inside the body of the request, and it is called the **payload** .

You can think of the payload as the “content of the package”: the request is the envelope, and the payload is what’s inside.

In this case, the payload is a **JSON** file that contains the necessary data to create a disk and attach it to a server.

***

## A practical example

We'll explain it using the following example

### The Endpoint We Will Use

The endpoint is:

/api/servers/v1/subscriptions/\[subscriptionId]/disks

This endpoint is used to **create a new disk** inside a subscription and **attach it to a server**.

**What Is** \[subscriptionId]? This value is part of the URL, not the payload. It means you must replace \[subscriptionId] with the actual ID of your subscription.

Example:

/api/servers/v1/subscriptions/abc123/disks

***

### What Goes Inside the Payload?

The JSON payload you send must include these parameters:

**serverId** → The ID of the server where the disk will be attached

**name** → The name you want to give the disk

**zone** → The zone where the disk will be created

**size** → The disk size (for example, 25 GB)

Here is the base JSON model:

JSON

```json
{
  "serverId": null,
  "name": null,
  "zone": "",
  "size": 25
}
```

In a real request, you would replace the values, for example:

```json
{
  "serverId": "srv-12345",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}
```

***

### Required Headers in the Request

<br>

Besides the payload, your request must include specific headers so the API can process it correctly:

Authorization: Bearer \[your-access-token] Accept: application/json Content-Type: application/json

These headers have the following purpose:

**Authorization** → Identifies you using an access **token**

**Accept** → Tells the API that you want the response in JSON

**Content-Type** → Indicates that your payload is also in JSON

***

### Full cURL Example

Here is a complete **POST** request using cURL:

Bash

```curl
curl -X POST "https://your-domain.com/api/servers/v1/subscriptions/abc123/disks" \
  -H "Authorization: Bearer my-secret-token" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
        "serverId": "srv-12345",
        "name": "secondary-data",
        "zone": "eu-madrid-1",
        "size": 25
      }'
```

**What’s happening here?**

* -X POST → You are telling the API you want to **create** something.
* The \*\*URL \*\* includes the \[subscriptionId] (abc123).
* The -H lines send the required **headers** .
* The -d block sends the **payload** as a JSON object.

***

### Example for Windows in PowerShell

Below is the **same request using** curl.exe **in Windows PowerShell** . It sends a POST request to create a disk and attach it to a server, including the required headers and a JSON payload.

PowerShell

```powershell
$subscriptionId = "abc123"
$token = "my-secret-token"
$baseUrl = "https://your-domain.com"
$endpoint = "/api/servers/v1/subscriptions/$subscriptionId/disks"
$url = "$baseUrl$endpoint"

# JSON body as a here-string (easier to write without escaping quotes)
$jsonBody = @'
{
  "serverId": "srv-12345",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}
'@

# POST request with curl.exe
curl.exe -X POST $url `
  -H "Authorization: Bearer $token" `
  -H "Accept: application/json" `
  -H "Content-Type: application/json" `
  -d $jsonBody
```

**What this does**

* Puts subscriptionId in the URL (not in the JSON).
* Sends the Authorization header with your access token.
* Sets Accept: application/json and Content-Type: application/json.
* Sends the payload (JSON) with the required fields: serverId, name, zone, size.

**Optional tip**

If you want to insert variables directly into the JSON, use an expandable here‑string (@" ... "@) instead of the literal one:

PowerShell

```powershell
$serverId = "srv-12345"
$jsonBody = @"
{
  "serverId": "$serverId",
  "name": "secondary-data",
  "zone": "eu-madrid-1",
  "size": 25
}
"@
```

<br>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.plenit.com/docs-en/reference/getting-started/beginners-guide-payload-headers-and-example-request.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.