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.
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).
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.
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:
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.
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.
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
source
: blockdata
: 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
: nonerespondedToBy
: openaiCreateImageResponsesentOnInitialization
: false
openaiCreateImageResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
created | number | yes | |
data | object[] | yes |
errorCodes
: FORBIDDEN
, INTERNAL_ERROR
, INVALID_INPUT
, NOT_IMPLEMENTED
, TOO_MANY_REQUESTS
, UNAUTHORIZED
respondedToBy
: nonesentOnInitialization
: false
openaiCompleteText
source
: blockdata
: 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
: nonerespondedToBy
: openaiCompleteTextResponsesentOnInitialization
: false
openaiCompleteTextResponse
source
: embedderdata
: 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
: nonesentOnInitialization
: false
openaiCompleteChat
source
: blockdata
: 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
: nonerespondedToBy
: openaiCompleteChatResponsesentOnInitialization
: false
openaiCompleteChatResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
id | string | yes | |
object | string | yes | |
created | number | yes | |
model | string | yes | |
choices | object[] | yes | |
usage | object | no |
errorCodes
: nonerespondedToBy
: nonesentOnInitialization
: false
mapboxForwardGeocoding
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
searchText | string | yes | |
optionsArg | object | no |
errorCodes
: nonerespondedToBy
: mapboxForwardGeocodingResponsesentOnInitialization
: false
mapboxForwardGeocodingResponse
source
: embedderdata
: 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
: nonesentOnInitialization
: false
mapboxReverseGeocoding
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
lngLat | yes | ||
optionsArg | object | no |
errorCodes
: nonerespondedToBy
: mapboxReverseGeocodingResponsesentOnInitialization
: false
mapboxReverseGeocodingResponse
source
: embedderdata
: 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
: nonesentOnInitialization
: false
mapboxRetrieveDirections
source
: blockdata
:
errorCodes
: nonerespondedToBy
: mapboxRetrieveDirectionsResponsesentOnInitialization
: false
mapboxRetrieveRetrieveDirectionsResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
code | string | yes | |
routes | [] | yes |
errorCodes
: FORBIDDEN
, INTERNAL_ERROR
, INVALID_INPUT
, NOT_IMPLEMENTED
, TOO_MANY_REQUESTS
, UNAUTHORIZED
respondedToBy
: nonesentOnInitialization
: false
mapboxRetrieveIsochrones
source
: blockdata
: 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
: nonerespondedToBy
: mapboxRetrieveIsochronesResponsesentOnInitialization
: false
mapboxRetrieveIsochronesResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
features | [] | yes |
errorCodes
: FORBIDDEN
, INTERNAL_ERROR
, INVALID_INPUT
, NOT_IMPLEMENTED
, TOO_MANY_REQUESTS
, UNAUTHORIZED
respondedToBy
: nonesentOnInitialization
: false
mapboxSuggestAddress
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
searchText | string | yes | |
optionsArg | yes |
errorCodes
: nonerespondedToBy
: mapboxSuggestAddressResponsesentOnInitialization
: false
mapboxSuggestAddressResponse
source
: embedderdata
: 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
: nonesentOnInitialization
: false
mapboxRetrieveAddress
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
suggestion | object | yes | |
optionsArg | yes |
errorCodes
: nonerespondedToBy
: mapboxRetrieveAddressResponsesentOnInitialization
: false
mapboxRetrieveAddressResponse
source
: embedderdata
: 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
: nonesentOnInitialization
: false
mapboxCanRetrieveAddress
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
suggestion | object | yes |
errorCodes
: nonerespondedToBy
: mapboxCanRetrieveAddressResponsesentOnInitialization
: false
mapboxCanRetrieveAddressResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
canRetrieveAddress | boolean | yes |
errorCodes
: FORBIDDEN
, INTERNAL_ERROR
, INVALID_INPUT
, NOT_IMPLEMENTED
, TOO_MANY_REQUESTS
, UNAUTHORIZED
respondedToBy
: nonesentOnInitialization
: false
mapboxRetrieveStaticMap
source
: blockdata
: object
property | type | required | description |
---|---|---|---|
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
: nonerespondedToBy
: mapboxRetrieveStaticMapResponsesentOnInitialization
: false
mapboxRetrieveStaticMapResponse
source
: embedderdata
: object
property | type | required | description |
---|---|---|---|
type | string | yes | |
data | object | yes |
errorCodes
: FORBIDDEN
, INTERNAL_ERROR
, INVALID_INPUT
, NOT_IMPLEMENTED
, TOO_MANY_REQUESTS
, UNAUTHORIZED
respondedToBy
: nonesentOnInitialization
: false
Previous
Next
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.
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.