Invoke through the REST API

The Golem REST API exposes two endpoints for invoking agents. See the Worker REST API reference for details. These endpoints provide a direct, low level API for calling the exported functions of the agents. They use a special JSON format for encoding WASM values and types. It is possible, and recommended, to create custom HTTP APIs for exposing agents to the world.

Endpoints

Invoke agents

The invoke endpoint enqueues an invocation for the given agent and returns immediately.

POST /v1/components/{component_id}/workers/{agent_id}/invoke?function={function_name}

This POST request invokes the agent called agent_id of the component identified by component_id (a UUID), calling the function function_name. Read the name mapping page to learn how the function names are mapped.

The body of the POST request must be a JSON object containing a single field called params, which is an array of typed JSON values. The format of typed JSON values is described below.

Invoke and await agents

The invoke-and-await endpoint enqueues an invocation for a given agent and then awaits its completion, returning the successful result value or failure in the response body.

POST /v1/components/{component_id}/workers/{agent_id}/invoke-and-await?function={function_name}

This POST request invokes the agent called agent_id (consisting of the agent type name and the parameter values) of the component identified by component_id (a UUID), calling the function function_name. Read the name mapping page to learn how the function names are mapped.

The body of the POST request must be a JSON object containing a single field called params, which is an array of typed JSON values. The format of typed JSON values is described below.

The response body is a JSON object with a single field result, containing the invoked function's result encoded as a typed JSON value.

Implicit agent creation

If the invoked agent does not exist, it is automatically created by the invocation.

Cancelling pending invocations

As invocations are executed sequentially, it is possible to cancel a pending invocation before it starts executing. This can be done using the cancel invocation endpoint:

DELETE /v1/components/{component_id}/workers/{agent_id}/invocations/{idempotency_key}

Typed JSON values

Typed JSON values are JSON objects with two fields:

• typ describes the type of the value
• value is the actual value

The invocation API does not require type information beside the values, but providing it makes the invocation much faster. Invocations without provided type information are intended to be used only for testing, as they involve gathering the missing information for each invocation separately.

Value format

Read the Type Mapping page to see how every WebAssembly value is encoded in JSON, and how the data types defined in the Golem component's source code are mapped to these.

Getting the type

When constructing invocation requests, the easiest way to get the type part of the request body is to get the component metadata using the REST API:

GET /v1/components/{component_id}/latest

This request returns the metadata of the latest version of the component given by its identifier (a UUID). This metadata lists all the exported functions and their expected parameter types. These parameter types encode type information in the same format as the invocation API, so it is possible to copy them when constructing invocations.

Note that it is not recommended to do this dynamically; the client using the invocation API should target a specific component version, with parameter types known in advance.