Service Module

This document (version 0.1) defines a service module according to the terms set out in the core specification.

The service module enables blocks to interact with external services without needing to be provided with credentials: the embedding application calls the external service on the block's behalf.

Glossary

Provider: a company, organization or person that provides a service or services (e.g. Mapbox)

Service: a request handler which meets a specific functional goal, typically external to the embedding application and accessed via third-party API endpoint or integration (e.g. Retrieve Address).

Messages

Handling messages

Summary

Any messages exchanged between application and block should be consistent with the shape and intent of the messages as described in this specification.

While the messages are based on APIs available from external service providers, how exactly the embedding application generates responses to the block is beyond the scope of the Block Protocol, so long as the schema and intent of the message as described in this specification are met – i.e. the embedding application need not call the external service provider if they have another means of generating an appropriate response.

Specification

Embedding applications MUST ensure that any responses they provide to blocks to messages sent under the service module are consistent with the schema and described intent of the message in this specification, and consistent with the response that the named service provider would return, except for any fields which are required by the named service provider but omitted from this specification (e.g. because they relate to authentication or other information that the block should not or does not have access to, and which can be added by the embedding application when making a request to an external service provider in order to produce a response for the block).

Embedding applications MAY generate a response to a block's message by doing any of the following:

calling the external service provider directly (augmenting the block's original request with any additional fields or headers the service provider requires), OR
generating the response internally, OR
calling a third party that provides an appropriate response, whether the third party generates this response directly or by themselves making a request to the named service provider.

Error definitions

Specification

If a request fails, embedding applications MUST provide blocks with an error which complies with this specification, i.e. contains a listed code and a message.

Embedding applications MAY withhold or translate error codes and messages sent by the service provider when reporting an error to the block.

Blocks MUST NOT rely on error codes and messages providing information that the named service provider would if contacted directly, e.g. relating to billing.

Message definitions

Summary

The message signatures in the service specification aim to be as consistent as possible with the equivalent requests and responses from the named service provider, subject to exceptions mentioned elsewhere in this specification.

Specification

The messages available for exchange in the service module are defined in the module's JSON definition and are also listed below for ease of reference.

openaiCreateImage[block]

openaiCreateImageResponse[embedder]

openaiCompleteText[block]

openaiCompleteTextResponse[embedder]

openaiCompleteChat[block]

openaiCompleteChatResponse[embedder]

mapboxForwardGeocoding[block]

mapboxForwardGeocodingResponse[embedder]

mapboxReverseGeocoding[block]

mapboxReverseGeocodingResponse[embedder]

mapboxRetrieveDirections[block]

mapboxRetrieveRetrieveDirectionsResponse[embedder]

mapboxRetrieveIsochrones[block]

mapboxRetrieveIsochronesResponse[embedder]

mapboxSuggestAddress[block]

mapboxSuggestAddressResponse[embedder]

mapboxRetrieveAddress[block]

mapboxRetrieveAddressResponse[embedder]

mapboxCanRetrieveAddress[block]

mapboxCanRetrieveAddressResponse[embedder]

mapboxRetrieveStaticMap[block]

mapboxRetrieveStaticMapResponse[embedder]

`openaiCreateImage`

Create an image using OpenAI - see https://platform.openai.com/docs/api-reference/images

source: block

data: object

property	type	required	description
`size`	string	no	The size of the generated images. Must be one of `256x256`, `512x512`, or `1024x1024`.
`prompt`	string	yes	A text description of the desired image(s). The maximum length is 1000 characters.
`n`	number	no	The number of images to generate. Must be between 1 and 10.
`response_format`	string	no	The format in which the generated images are returned. Must be one of `url` or `b64_json`.

errorCodes: none
respondedToBy: openaiCreateImageResponse
sentOnInitialization: false

`openaiCreateImageResponse`

Response to a create OpenAI image request

source: embedder
data: object
property type required description
created number yes
data object[] yes
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`created`	number	yes
`data`	object[]	yes

`openaiCompleteText`

Complete text using OpenAI – see https://platform.openai.com/docs/api-reference/completions

source: block

data: object

property	type	required	description
`stop`		no	Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence.
`prompt`		no	The prompt(s) to generate completions for, encoded as a string, array of strings, array of tokens, or array of token arrays. Note that <\|endoftext\|> is the document separator that the model sees during training, so if a prompt is not specified the model will generate as if from the beginning of a new document.
`n`	number	no	How many completions to generate for each prompt. Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
`model`	string	yes	ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models/overview) for descriptions of them.
`suffix`	string	no	The suffix that comes after a completion of inserted text.
`max_tokens`	number	no	The maximum number of [tokens](/tokenizer) to generate in the completion. The token count of your prompt plus `max_tokens` cannot exceed the model\'s context length. Most models have a context length of 2048 tokens (except for the newest models, which support 4096).
`temperature`	number	no	What [sampling temperature](https://towardsdatascience.com/how-to-sample-from-language-models-682bceb97277) to use. Higher values means the model will take more risks. Try 0.9 for more creative applications, and 0 (argmax sampling) for ones with a well-defined answer. We generally recommend altering this or `top_p` but not both.
`top_p`	number	no	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
`stream`	boolean	no	Whether to stream back partial progress. If set, tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message.
`logprobs`	number	no	Include the log probabilities on the `logprobs` most likely tokens, as well the chosen tokens. For example, if `logprobs` is 5, the API will return a list of the 5 most likely tokens. The API will always return the `logprob` of the sampled token, so there may be up to `logprobs+1` elements in the response. The maximum value for `logprobs` is 5. If you need more than this, please contact us through our [Help center](https://help.openai.com) and describe your use case.
`echo`	boolean	no	Echo back the prompt in addition to the completion
`presence_penalty`	number	no	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model\'s likelihood to talk about new topics. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
`frequency_penalty`	number	no	Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model\'s likelihood to repeat the same line verbatim. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
`best_of`	number	no	Generates `best_of` completions server-side and returns the \"best\" (the one with the highest log probability per token). Results cannot be streamed. When used with `n`, `best_of` controls the number of candidate completions and `n` specifies how many to return – `best_of` must be greater than `n`. Note: Because this parameter generates many completions, it can quickly consume your token quota. Use carefully and ensure that you have reasonable settings for `max_tokens` and `stop`.
`logit_bias`	object	no	Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the GPT tokenizer) to an associated bias value from -100 to 100. You can use this [tokenizer tool](/tokenizer?view=bpe) (which works for both GPT-2 and GPT-3) to convert text to token IDs. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token. As an example, you can pass `{\"50256\": -100}` to prevent the <\|endoftext\|> token from being generated.

errorCodes: none
respondedToBy: openaiCompleteTextResponse
sentOnInitialization: false

`openaiCompleteTextResponse`

Response to a OpenAI complete text request

source: embedder
data: object
property type required description
id string yes
object string yes
created number yes
model string yes
choices object[] yes
usage object no
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required
`id`	string	yes
`object`	string	yes
`created`	number	yes
`model`	string	yes
`choices`	object[]	yes
`usage`	object	no

`openaiCompleteChat`

Complete a chat using OpenAI

source: block

data: object

property	type	required	description
`stop`		no	Up to 4 sequences where the API will stop generating further tokens.
`n`	number	no	How many chat completion choices to generate for each input message.
`model`	string	yes	ID of the model to use. Currently, only `gpt-3.5-turbo` and `gpt-3.5-turbo-0301` are supported.
`max_tokens`	number	no	The maximum number of tokens allowed for the generated answer. By default, the number of tokens the model can return will be (4096 - prompt tokens).
`temperature`	number	no	What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic. We generally recommend altering this or `top_p` but not both.
`top_p`	number	no	An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
`stream`	boolean	no	If set, partial message deltas will be sent, like in ChatGPT. Tokens will be sent as data-only [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format) as they become available, with the stream terminated by a `data: [DONE]` message.
`presence_penalty`	number	no	Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model\'s likelihood to talk about new topics. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
`frequency_penalty`	number	no	Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model\'s likelihood to repeat the same line verbatim. [See more information about frequency and presence penalties.](/docs/api-reference/parameter-details)
`logit_bias`	object	no	Modify the likelihood of specified tokens appearing in the completion. Accepts a json object that maps tokens (specified by their token ID in the tokenizer) to an associated bias value from -100 to 100. Mathematically, the bias is added to the logits generated by the model prior to sampling. The exact effect will vary per model, but values between -1 and 1 should decrease or increase likelihood of selection; values like -100 or 100 should result in a ban or exclusive selection of the relevant token.
`messages`	object[]	yes	The messages to generate chat completions for, in the [chat format](/docs/guides/chat/introduction).

errorCodes: none
respondedToBy: openaiCompleteChatResponse
sentOnInitialization: false

`openaiCompleteChatResponse`

Response to a OpenAI complete text request

source: embedder
data: object
property type required description
id string yes
object string yes
created number yes
model string yes
choices object[] yes
usage object no
errorCodes: none
respondedToBy: none
sentOnInitialization: false

property	type	required
`id`	string	yes
`object`	string	yes
`created`	number	yes
`model`	string	yes
`choices`	object[]	yes
`usage`	object	no

`mapboxForwardGeocoding`

Forward geocoding request – see https://docs.mapbox.com/api/search/geocoding

source: block
data: object
property type required description
searchText string yes
optionsArg object no
errorCodes: none
respondedToBy: mapboxForwardGeocodingResponse
sentOnInitialization: false

property	type	required	description
`searchText`	string	yes
`optionsArg`	object	no

`mapboxForwardGeocodingResponse`

Response to a forward geocoding request

source: embedder

data: object

property	type	required	description
`type`	string	yes	`"FeatureCollection"`, a GeoJSON type from the [GeoJSON specification](https://tools.ietf.org/html/rfc7946).
`query`	string[]	yes	Forward geocodes: An array of space and punctuation-separated strings from the original query. Reverse geocodes: An array containing the coordinates being queried.
`features`	[]	yes	The returned feature objects.
`attribution`	string	yes	Attributes the results of the Mapbox Geocoding API to Mapbox.

errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

`mapboxReverseGeocoding`

Reverse geocoding request – see https://docs.mapbox.com/api/search/geocoding

source: block
data: object
property type required description
lngLat yes
optionsArg object no
errorCodes: none
respondedToBy: mapboxReverseGeocodingResponse
sentOnInitialization: false

property	type	required	description
`lngLat`		yes
`optionsArg`	object	no

`mapboxReverseGeocodingResponse`

The response to a request geocoding request

source: embedder

data: object

property	type	required	description
`type`	string	yes	`"FeatureCollection"`, a GeoJSON type from the [GeoJSON specification](https://tools.ietf.org/html/rfc7946).
`query`	string[]	yes	Forward geocodes: An array of space and punctuation-separated strings from the original query. Reverse geocodes: An array containing the coordinates being queried.
`features`	[]	yes	The returned feature objects.
`attribution`	string	yes	Attributes the results of the Mapbox Geocoding API to Mapbox.

errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

`mapboxRetrieveDirections`

Retrieve directions request – see https://docs.mapbox.com/api/navigation/directions

source: block
data:
errorCodes: none
respondedToBy: mapboxRetrieveDirectionsResponse
sentOnInitialization: false

`mapboxRetrieveRetrieveDirectionsResponse`

The response to a retrieve directions request

source: embedder
data: object
property type required description
code string yes
routes [] yes
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`code`	string	yes
`routes`	[]	yes

`mapboxRetrieveIsochrones`

Retrieve isochrones – see https://docs.mapbox.com/api/navigation/isochrone

source: block
data: object
property type required description
profile string yes
coordinates array[] yes
contours_minutes number yes
contours_meters number yes
contours_colors string no
polygons boolean no
denoise number no
generalize number no
errorCodes: none
respondedToBy: mapboxRetrieveIsochronesResponse
sentOnInitialization: false

property	type	required
`profile`	string	yes
`coordinates`	array[]	yes
`contours_minutes`	number	yes
`contours_meters`	number	yes
`contours_colors`	string	no
`polygons`	boolean	no
`denoise`	number	no
`generalize`	number	no

`mapboxRetrieveIsochronesResponse`

The response to a retrieve isochrones request

source: embedder
data: object
property type required description
features [] yes
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`features`	[]	yes

`mapboxSuggestAddress`

Suggest an address – see https://docs.mapbox.com/api/search/search/#retrieve-a-suggestion

source: block
data: object
property type required description
searchText string yes
optionsArg yes
errorCodes: none
respondedToBy: mapboxSuggestAddressResponse
sentOnInitialization: false

property	type	required	description
`searchText`	string	yes
`optionsArg`		yes

`mapboxSuggestAddressResponse`

The response to a request to suggest an address

source: embedder
data: object
property type required description
attribution string no The attribution data for results.
suggestions object[] yes The returned suggestion objects.
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`attribution`	string	no	The attribution data for results.
`suggestions`	object[]	yes	The returned suggestion objects.

`mapboxRetrieveAddress`

Retrieve an address - see https://docs.mapbox.com/api/search/search/#retrieve-a-suggested-feature

source: block
data: object
property type required description
suggestion object yes
optionsArg yes
errorCodes: none
respondedToBy: mapboxRetrieveAddressResponse
sentOnInitialization: false

property	type	required	description
`suggestion`	object	yes
`optionsArg`		yes

`mapboxRetrieveAddressResponse`

The response to a retrieve an address

source: embedder
data: object
property type required description
type string yes
attribution string no The attribution data for results.
features [] yes The returned feature objects.
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`type`	string	yes
`attribution`	string	no	The attribution data for results.
`features`	[]	yes	The returned feature objects.

`mapboxCanRetrieveAddress`

Whether an address can be retrieved

source: block
data: object
property type required description
suggestion object yes
errorCodes: none
respondedToBy: mapboxCanRetrieveAddressResponse
sentOnInitialization: false

property	type	required	description
`suggestion`	object	yes

`mapboxCanRetrieveAddressResponse`

The response to a can retrieve an address request

source: embedder
data: object
property type required description
canRetrieveAddress boolean yes
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`canRetrieveAddress`	boolean	yes

`mapboxRetrieveStaticMap`

Retrieve a static map – see https://docs.mapbox.com/api/maps/static-images

source: block

data: object

property	type	required
`username`	string	yes
`style_id`	string	yes
`overlay`	string	yes
`lon`	number	yes
`lat`	number	yes
`zoom`	number	yes
`bbox`		yes
`auto`	string	yes
`width`	number	yes
`height`	number	yes
`bearing`	number	no
`pitch`	number	no
`@2x`	string	no
`attribution`	boolean	no
`logo`	boolean	no
`before_layer`	string	no
`addlayer`	object	no
`setfilter`	string[]	no
`layer_id`	string	no
`padding`	string	no

errorCodes: none
respondedToBy: mapboxRetrieveStaticMapResponse
sentOnInitialization: false

`mapboxRetrieveStaticMapResponse`

The response to a retrieve static map request

source: embedder
data: object
property type required description
type string yes
data object yes
errorCodes: FORBIDDEN, INTERNAL_ERROR, INVALID_INPUT, NOT_IMPLEMENTED, TOO_MANY_REQUESTS, UNAUTHORIZED
respondedToBy: none
sentOnInitialization: false

property	type	required	description
`type`	string	yes
`data`	object	yes

Hook Module

Roadmap

Add blocks to your app

Anyone with an existing application who wants to embed semantically-rich, reusable blocks in their product can use the protocol. Improve your app’s utility and tap into a world of structured data with no extra effort, for free.

Learn more

Build your own blocks

Any developer can build and publish blocks to the Hub for others to use. Contribute to an open-source community building a more interoperable future web.

Read the quickstart guide

Service Module

Glossary

Messages

Handling messages

Handling messages Summary

Handling messages Specification

Error definitions

Error definitions Specification

Message definitions

Message definitions Summary

Message definitions Specification

openaiCreateImage

openaiCreateImageResponse

openaiCompleteText

openaiCompleteTextResponse

openaiCompleteChat

openaiCompleteChatResponse

mapboxForwardGeocoding

mapboxForwardGeocodingResponse

mapboxReverseGeocoding

mapboxReverseGeocodingResponse

mapboxRetrieveDirections

mapboxRetrieveRetrieveDirectionsResponse

mapboxRetrieveIsochrones

mapboxRetrieveIsochronesResponse

mapboxSuggestAddress

mapboxSuggestAddressResponse

mapboxRetrieveAddress

mapboxRetrieveAddressResponse

mapboxCanRetrieveAddress

mapboxCanRetrieveAddressResponse

mapboxRetrieveStaticMap

mapboxRetrieveStaticMapResponse

Add blocks to your app

Build your own blocks

Summary

Specification

Specification

Summary

Specification

`openaiCreateImage`

`openaiCreateImageResponse`

`openaiCompleteText`

`openaiCompleteTextResponse`

`openaiCompleteChat`

`openaiCompleteChatResponse`

`mapboxForwardGeocoding`

`mapboxForwardGeocodingResponse`

`mapboxReverseGeocoding`

`mapboxReverseGeocodingResponse`

`mapboxRetrieveDirections`

`mapboxRetrieveRetrieveDirectionsResponse`

`mapboxRetrieveIsochrones`

`mapboxRetrieveIsochronesResponse`

`mapboxSuggestAddress`

`mapboxSuggestAddressResponse`

`mapboxRetrieveAddress`

`mapboxRetrieveAddressResponse`

`mapboxCanRetrieveAddress`

`mapboxCanRetrieveAddressResponse`

`mapboxRetrieveStaticMap`

`mapboxRetrieveStaticMapResponse`