# Golem HTTP Params Moonbit

> Mapping path, query, header, and body parameters for HTTP endpoints in MoonBit Golem agents. Use when configuring how HTTP request data maps to agent method parameters.

- Skill: `golemcloud/golem-http-params-moonbit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add golemcloud/golem-http-params-moonbit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/golemcloud/golem-http-params-moonbit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: golemcloud (https://skillmd.com/u/golemcloud)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/golemcloud/golem-http-params-moonbit

---


# HTTP Request and Response Parameter Mapping (MoonBit)

## Overview

When an agent is exposed over HTTP, Golem maps parts of each HTTP request to constructor and method parameters. This skill covers how path segments, query parameters, headers, and request bodies are mapped, which types are supported for each, and how return types map to HTTP responses.

## Path Variables

Path variables `{var_name}` in mount or endpoint paths map to parameters by name:

```moonbit
///|
/// A task management agent
#derive.agent
#derive.mount("/api/tasks/{task_name}")
pub(all) struct TaskAgent {
  task_name : String
}

///|
fn TaskAgent::new(task_name : String) -> TaskAgent {
  { task_name }
}

///|
/// Get an item by ID
#derive.endpoint(get="/items/{item_id}")
pub fn TaskAgent::get_item(self : Self, item_id : String) -> Item {
  // task_name from mount path, item_id from endpoint path
  ...
}
```

Remaining (catch-all) path variables capture everything after a prefix:

```moonbit
#derive.endpoint(get="/files/{*path}")
pub fn TaskAgent::get_file(self : Self, path : String) -> FileContent {
  // GET .../files/docs/readme.md → path = "docs/readme.md"
  ...
}
```

Catch-all variables can only appear as the **last** path segment and are **not** allowed in mount paths.

## Query Parameters

Specified in the endpoint path using `?key={var}` syntax:

```moonbit
#derive.endpoint(get="/search?q={query}&limit={max_results}")
pub fn TaskAgent::search(self : Self, query : String, max_results : UInt64) -> Array[SearchResult] {
  // GET .../search?q=hello&limit=10
  ...
}
```

## Header Variables

Map HTTP headers to parameters using `#derive.endpoint_header`:

```moonbit
#derive.endpoint(get="/data")
#derive.endpoint_header("X-Request-Id", "request_id")
#derive.endpoint_header("Authorization", "token")
pub fn TaskAgent::get_data(self : Self, request_id : String, token : String) -> Data {
  ...
}
```

Each `#derive.endpoint_header` maps one header to one method parameter. Duplicate header names (case-insensitive) are not allowed.

## Supported Types for Path, Query, and Header Variables

Only these types can be used for parameters bound to path/query/header variables (the value is parsed from the URL/header string):

| MoonBit Type | Parsed From |
|---|---|
| `String` | Used as-is |
| `Char` | Single character |
| `Bool` | Parsed from `"true"` / `"false"` |
| `UInt`, `UInt64` | Parsed as unsigned integer |
| `Int`, `Int64` | Parsed as signed integer |
| `Double` | Parsed as floating-point number |
| Enum (unit variants only) | Matched against known case names |

**For query parameters and headers only** (not path variables), two additional wrapper types are supported:

| MoonBit Type | Behavior |
|---|---|
| `T?` (`Option[T]`, where `T` is a supported type above) | Optional — absent query param or header produces `None` |
| `Array[T]` (where `T` is a supported type above) | Repeated query params or comma-separated header values |

**All other types** (structs, tuples, enums with data, etc.) can only be used as **body parameters**.

## POST Request Body Mapping

For `POST`/`PUT`/`DELETE` endpoints, method parameters **not** bound to path variables, query parameters, or headers are populated from the JSON request body:

```moonbit
#derive.endpoint(post="/items/{id}")
pub fn TaskAgent::update_item(self : Self, id : String, name : String, count : UInt64) -> Item {
  // POST .../items/123
  // Body: { "name": "Widget", "count": 5 }
  // → id from path, name and count from body
  ...
}
```

Each unmapped parameter becomes a top-level field in the expected JSON body object. All custom types must have `#derive.golem_schema`.

> **⚠️ Important:** The request body is **always** a JSON object with parameter names as keys — even when there is only a single body parameter. For example, an endpoint `decide(self : Self, decision : String)` expects `{"decision": "approved"}`, **never** a bare string like `"approved"`. Sending a non-object JSON value or plain text will fail with `REQUEST_JSON_BODY_PARSING_FAILED`.

## Binary Request and Response Bodies

Use `UnstructuredBinary` from the SDK for raw binary payloads:

```moonbit
///|
/// Accepting any binary content type
#derive.endpoint(post="/upload/{bucket}")
pub fn TaskAgent::upload(self : Self, bucket : String, payload : UnstructuredBinary) -> Int64 {
  match payload {
    Url(_) => -1L
    Inline(data~, mime_type~) => data.length().to_int64()
  }
}

///|
/// Restricting to specific MIME types
#derive.endpoint(post="/upload-image/{bucket}")
#derive.mime_types("payload", "image/png", "image/jpeg")
pub fn TaskAgent::upload_image(self : Self, bucket : String, payload : UnstructuredBinary) -> Int64 {
  match payload {
    Url(_) => -1L
    Inline(data~, mime_type~) => data.length().to_int64()
  }
}

///|
/// Returning binary data
#derive.endpoint(get="/download")
pub fn TaskAgent::download(self : Self) -> UnstructuredBinary {
  UnstructuredBinary::from_inline(b"\x01\x02\x03\x04", mime_type="application/octet-stream")
}
```

`UnstructuredBinary` parameters cannot be bound to path, query, or header variables.

## Plain Text Request and Response Bodies

Use `UnstructuredText` from the SDK for raw `text/plain` payloads. Like
`UnstructuredBinary`, a method using `UnstructuredText` may have **only one
body parameter**, and that parameter cannot be bound to a path/query/header/mount
variable. The body is decoded as UTF-8.

```moonbit
///|
/// Accepting any text/plain content
#derive.endpoint(post="/notes/{id}")
pub fn TaskAgent::add_note(self : Self, id : String, body : UnstructuredText) -> UInt64 {
  match body {
    Url(_) => 0UL
    Inline(data~, language_code~) => data.length().to_uint64()
  }
}

///|
/// Restricting to specific language codes
#derive.endpoint(post="/translate/{id}")
#derive.text_languages("body", "en", "de")
pub fn TaskAgent::translate(self : Self, id : String, body : UnstructuredText) -> String {
  match body {
    Url(_) => ""
    Inline(data~, ..) => data
  }
}

///|
/// Returning text/plain
#derive.endpoint(get="/notes/{id}")
pub fn TaskAgent::get_note(self : Self, id : String) -> UnstructuredText {
  UnstructuredText::from_inline("hello", language_code=Some("en"))
}
```

HTTP-level rules:
- The request must have either no `Content-Type`, `text/plain`, or
  `text/plain; charset=utf-8` (case-insensitive). Any other content type is
  rejected with `415 Unsupported Media Type`.
- `Content-Language` is **always optional**, even when language codes are
  restricted via `#derive.text_languages`. If present, it must be a single
  value (multi-valued or comma-separated headers are rejected with
  `400 Bad Request`).
- When restricted, the supplied `Content-Language` is matched
  case-insensitively against the allowed list; otherwise `415 Unsupported Media Type`.
- A non-UTF-8 request body is rejected with `400 Bad Request`.
- `Content-Language` cannot also be bound as an endpoint header parameter when
  the body is `UnstructuredText` — that header is reserved for declaring the
  body language.

The response is sent as `Content-Type: text/plain; charset=utf-8`. If the
returned `UnstructuredText` (inline form) carries a language code, it is
forwarded as the `Content-Language` response header.

## Return Type to HTTP Response Mapping

| Return Type | HTTP Status | Response Body |
|---|---|---|
| `Unit` (no return) | 204 No Content | empty |
| `T` (any type) | 200 OK | JSON-serialized `T` |
| `T?` (`Option[T]`) | 200 OK if `Some`, 404 Not Found if `None` | JSON `T` or empty |
| `Result[T, E]` | 200 OK if `Ok`, 500 Internal Server Error if `Err` | JSON `T` or JSON `E` |
| `Result[Unit, E]` | 204 No Content if `Ok`, 500 if `Err` | empty or JSON `E` |
| `UnstructuredBinary` | 200 OK | Raw binary with Content-Type |
| `UnstructuredText` | 200 OK | `text/plain; charset=utf-8` (+ optional `Content-Language`) |

## Data Type to JSON Mapping

| MoonBit Type | JSON Representation |
|---|---|
| `String` | JSON string |
| `Int`, `Int64`, `UInt`, `UInt64` | JSON number (integer) |
| `Double` | JSON number (float) |
| `Bool` | JSON boolean |
| `Array[T]` | JSON array |
| Struct (with `#derive.golem_schema`) | JSON object |
| `T?` (`Option[T]`) | value or `null` |
| `Result[T, E]` | value (see response mapping above) |
| Enum (unit variants) | JSON string |
| Enum (with data, `#derive.golem_schema`) | JSON object with tag |
| `(A, B, ...)` (tuple) | JSON array |

## Custom Types

All custom structs and enums used as parameters or return types must be annotated with `#derive.golem_schema`:

```moonbit
#derive.golem_schema
pub(all) enum Priority {
  Low
  Medium
  High
} derive(Eq)

#derive.golem_schema
pub(all) struct TaskInfo {
  title : String
  priority : Priority
  description : String?
}
```

## Complete Example

```moonbit
///|
/// A REST API agent exposing weather data via HTTP endpoints
#derive.agent
#derive.mount("/api/{city}/weather")
pub(all) struct WeatherAgent {
  city : String
  mut last_temperature : Double
}

///|
fn WeatherAgent::new(city : String) -> WeatherAgent {
  { city, last_temperature: 0.0 }
}

///|
/// Get current temperature
#derive.endpoint(get="/current?unit={unit}")
pub fn WeatherAgent::get_temperature(self : Self, unit : String) -> Double {
  if unit == "fahrenheit" {
    self.last_temperature * 9.0 / 5.0 + 32.0
  } else {
    self.last_temperature
  }
}

///|
/// Set the temperature
#derive.endpoint(post="/set")
#derive.endpoint_header("X-Source", "source")
pub fn WeatherAgent::set_temperature(
  self : Self,
  temperature : Double,
  source : String,
) -> String {
  self.last_temperature = temperature
  "Temperature set to " + temperature.to_string() + " from " + source
}
```


## Related Skills

- Load `golem-add-http-endpoint-moonbit` for the high-level workflow of defining and mounting HTTP endpoints on an agent