Make Custom HTTP APIs for your Golem App

Golem’s Gateway service not only exposes the low-level REST API for invocations but also provides a way to expose agent methods as HTTP APIs.

In Golem 1.5, HTTP endpoints are defined directly in agent code using language-native decorators and macros — no YAML route definitions or scripting languages needed.

Mount Points

Every agent that wants to expose HTTP endpoints must first define a mount point — the base URL prefix under which all its endpoints are available. The mount path can contain placeholders like {name} that map to the agent’s constructor parameters.

TypeScript


@agent({
  mount: '/task-agents/{name}',
})
export class Tasks extends BaseAgent {
  constructor(readonly name: string) { super(); }
  // ...
}

Rust


#[agent_definition(mount = "/task-agents/{name}")]
pub trait Tasks {
    fn new(name: String) -> Self;
    // ...
}

Scala


@agentDefinition(mount = "/task-agents/{name}")
trait Tasks extends BaseAgent {
  // ...
}

MoonBit


#derive.agent
#derive.mount("/task-agents/{name}")
pub(all) struct Tasks {
  // ...
}

If there are multiple agent constructor parameters, they all have to be mapped in the mount path.

Endpoints

Once the mount is defined, individual agent methods can be exposed as HTTP endpoints. Each endpoint specifies an HTTP method and a path suffix relative to the mount point. Path placeholders are mapped to method parameters. Parameters not mapped through the path or headers are taken from the request body.

TypeScript


@endpoint({ post: "/tasks" })
async createTask(request: CreateTaskRequest): Promise<Task> {
  // ...
}
 
@endpoint({ get: "/tasks" })
async getTasks(): Promise<Task[]> {
  // ...
}
 
@endpoint({ post: "/tasks/{id}/complete" })
async completeTask(id: number): Promise<Task | null> {
  // ...
}

Rust


#[endpoint(post = "/tasks")]
fn create_task(&mut self, request: CreateTaskRequest) -> Task;
 
#[endpoint(get = "/tasks")]
fn get_tasks(&self) -> Vec<Task>;
 
#[endpoint(post = "/tasks/{id}/complete")]
fn complete_task(&mut self, id: usize) -> Option<Task>;

Scala


@endpoint(method = "POST", path = "/tasks")
def createTask(request: CreateTaskRequest): Future[Task]
 
@endpoint(method = "GET", path = "/tasks")
def getTasks(): Future[Array[Task]]
 
@endpoint(method = "POST", path = "/tasks/{id}/complete")
def completeTask(id: Int): Future[Option[Task]]

MoonBit


#derive.endpoint(post = "/tasks")
pub fn Tasks::create_task(self : Self, request : CreateTaskRequest) -> Task {
  // ...
}
 
#derive.endpoint(get = "/tasks")
pub fn Tasks::get_tasks(self : Self) -> Array[Task] {
  // ...
}
 
#derive.endpoint(post = "/tasks/{id}/complete")
pub fn Tasks::complete_task(self : Self, id : UInt32) -> Option[Task] {
  // ...
}

Supported HTTP methods: get, post, put, delete, patch, head, options, connect, trace, and custom (for arbitrary method strings, TypeScript only).

Query Parameters

Query parameters can be bound to method parameters using standard HTTP query syntax in the endpoint path:

TypeScript


@endpoint({ get: "/search?q={query}&limit={limit}" })
async search(query: string, limit: number): Promise<SearchResult[]> {
  // ...
}

Rust


#[endpoint(get = "/search/{category}?limit={limit}&offset={offset}")]
fn search(&self, category: String, limit: u64, offset: u64) -> Vec<Item>;

Scala


@endpoint(method = "GET", path = "/search/{category}?limit={limit}&offset={offset}")
def search(category: String, limit: Int, offset: Int): Future[Array[Item]]

MoonBit


#derive.endpoint(get = "/search/{category}?limit={limit}&offset={offset}")
pub fn MyAgent::search(self : Self, category : String, limit : UInt64, offset : UInt64) -> Array[Item] {
  // ...
}

Header Mapping

Custom HTTP headers can be mapped to function parameters:

TypeScript


@endpoint({
  get: '/example',
  headers: { 'X-Foo': 'location', 'X-Bar': 'name' },
})
async example(location: string, name: string): Promise<string> {
  // ...
}

Rust


#[endpoint(get = "/example", headers("X-Foo" = "location", "X-Bar" = "name"))]
fn example(&self, location: String, name: String) -> String;

Scala


@endpoint(method = "GET", path = "/example")
def example(@header("X-Foo") location: String, @header("X-Bar") name: String): Future[String]

MoonBit


#derive.endpoint(get = "/example")
#derive.endpoint_header("X-Foo", "location")
#derive.endpoint_header("X-Bar", "name")
pub fn ExampleAgent::example(self : Self, location : String, name : String) -> String {
  // ...
}

Catch-all Path Segments

The {*variable} syntax captures all remaining path segments. It must be the last segment in the path:

TypeScript


@endpoint({ get: "/files/{*rest}" })
async serveFile(rest: string): Promise<FileData> {
  // ...
}

Rust


#[endpoint(get = "/rest/{*tail}")]
fn catch_all(&self, tail: String) -> String;

Scala


@endpoint(method = "GET", path = "/files/{*path}")
def serveFile(path: String): Future[FileData]

MoonBit


#derive.endpoint(get = "/files/{*path}")
pub fn MyAgent::serve_file(self : Self, path : String) -> FileData {
  // ...
}

Response Conventions

Return types control the HTTP response:

Return type	HTTP response
A value (e.g. `Task`)	`200 OK` with JSON body
`Option<T>` / `T \| null`	`Some`/non-null → `200`; `None`/`null` → `404 Not Found`
`Result<T, E>`	`Ok` → `200`; `Err` → `400 Bad Request` with JSON error
`void` / `()`	`204 No Content`

Binary Request Bodies

Use the UnstructuredBinary type to receive raw binary data in the request body:

TypeScript


@endpoint({ post: "/upload" })
async upload(file: UnstructuredBinary): Promise<number> {
  // ...
}

Rust


#[endpoint(post = "/upload")]
fn upload(&mut self, file: UnstructuredBinary) -> u64;

Scala


@endpoint(method = "POST", path = "/upload")
def upload(file: UnstructuredBinary): Future[Long]

MoonBit


#derive.endpoint(post = "/upload")
pub fn MyAgent::upload(self : Self, file : UnstructuredBinary) -> UInt64 {
  // ...
}

CORS

CORS can be configured at the mount level (applies to all endpoints) and optionally overridden per endpoint:

TypeScript


@agent({
  mount: '/api/{name}',
  cors: ['https://app.example.com'],
})
export class MyAgent extends BaseAgent {
  // All endpoints inherit the mount-level CORS setting
 
  @endpoint({ get: "/public", cors: ["*"] })
  async getPublic(): Promise<Data> {
    // This endpoint adds additional allowed origins
  }
}

Rust


#[agent_definition(mount = "/api/{name}", cors = ["https://app.example.com"])]
pub trait MyAgent {
    // All endpoints inherit the mount-level CORS setting
 
    #[endpoint(get = "/public", cors = ["*"])]
    fn get_public(&self) -> Data;
    // This endpoint adds additional allowed origins
}

Scala


@agentDefinition(mount = "/api/{name}", cors = Array("https://app.example.com"))
trait MyAgent extends BaseAgent {
  // All endpoints inherit the mount-level CORS setting
 
  @endpoint(method = "GET", path = "/public", cors = Array("*"))
  def getPublic(): Future[Data]
  // This endpoint adds additional allowed origins
}

MoonBit


#derive.agent
#derive.mount("/api/{name}")
#derive.mount_cors("https://app.example.com")
pub(all) struct MyAgent {
  // ...
}
 
// All endpoints inherit the mount-level CORS setting
 
#derive.endpoint(get = "/public")
#derive.endpoint_cors("*")
pub fn MyAgent::get_public(self : Self) -> Data {
  // This endpoint adds additional allowed origins
}

Per-endpoint CORS settings are unioned with the mount-level settings.

Authentication

Golem API gateway has built-in authentication support. Authentication can be enabled at the mount level or per endpoint using auth = true. See the API authentication page for setup details.

TypeScript


@agent({
  mount: '/secure/{name}',
  auth: true, // require auth on all endpoints
})
export class SecureAgent extends BaseAgent {
  // ...
}
 
// Or per-endpoint:
@endpoint({ get: "/admin", auth: true })
async adminOnly(principal: Principal): Promise<AdminData> {
  // principal contains the authenticated user's identity
}

Rust


// Mount-level: all endpoints require auth
#[agent_definition(mount = "/secure/{name}", auth = true)]
pub trait SecureAgent {
    // ...
}
 
// Or per-endpoint:
#[endpoint(get = "/admin", auth = true)]
fn admin_only(&self, principal: Principal) -> AdminData;
// principal contains the authenticated user's identity

Scala


// Mount-level: all endpoints require auth
@agentDefinition(mount = "/secure/{name}", auth = true)
trait SecureAgent extends BaseAgent {
  // ...
}
 
// Or per-endpoint:
@endpoint(method = "GET", path = "/admin", auth = true)
def adminOnly(principal: Principal): Future[AdminData]
// principal contains the authenticated user's identity

MoonBit


// Mount-level: all endpoints require auth
#derive.agent
#derive.mount("/secure/{name}")
#derive.mount_auth(true)
pub(all) struct SecureAgent {
  // ...
}
 
// Or per-endpoint:
#derive.endpoint(get = "/admin")
#derive.endpoint_auth(true)
pub fn SecureAgent::admin_only(self : Self, principal : Principal) -> AdminData {
  // principal contains the authenticated user's identity
}

When authentication is enabled, agent constructors and methods can optionally receive a Principal parameter containing information about the authenticated caller.

Phantom Agents

Endpoints can be served by phantom agents — ephemeral, stateless agents that are created for each request and discarded afterward. This is useful for gateway-like agents that dispatch to internal agents, allowing requests to be processed completely in parallel.

TypeScript


@agent({
  mount: '/gateway/{name}',
  phantomAgent: true,
})
export class Gateway extends BaseAgent {
  // A new instance is created per request
}

Rust


#[agent_definition(mount = "/gateway/{name}", phantom_agent = true)]
pub trait Gateway {
    // A new instance is created per request
}

Scala


@agentDefinition(mount = "/gateway/{name}", phantomAgent = true)
trait Gateway extends BaseAgent {
  // A new instance is created per request
}

MoonBit


#derive.agent
#derive.mount("/gateway/{name}")
#derive.mount_phantom(true)
pub(all) struct Gateway {
  // A new instance is created per request
}

Deployments

To make the code-first routes accessible, a deployment section is needed in the application manifest (golem.yaml). This maps agents to domains per environment:


httpApi:
  deployments:
    local:
    - domain: app-name.localhost:9006
      agents:
        Tasks: {}

You can specify which agents to deploy to which (sub)domains, organized by environment (e.g. local, staging, prod).

Deploying the API

Once the deployment is configured in golem.yaml, deploy with:


golem deploy

OpenAPI Specification

Golem automatically generates an OpenAPI specification from the code-first route definitions. Each deployment exposes an openapi.yaml endpoint:


curl http://app-name.localhost:9006/openapi.yaml

This returns a standard OpenAPI 3.0 specification describing all the deployed endpoints, including path parameters, request/response schemas, and more.

Troubleshooting

See the troubleshooting page for some common issues and their solutions.