Get live using custom ID

GET 
/bv/cms/v1/lives/:id:custom-id

Returns a specific live based on the specified custom ID.

---

• Returns a 404/NotFound error if the requested resource is not found.

Request

Path Parameters

id stringrequired

Required. The custom id of the live.

Header Parameters

x-bv-org-id stringrequired

To invoke this API using api_token, you need to set the x-bv-org-id header to specify the organization for which you want to perform the action.

Responses

200

A successful response.

application/json

Schema

Schema

live object
id uuid
Output only. The unique id of the live.
name string
Possible values: <= 100 characters
Optional. The name of the live.
custom_id string
Possible values: non-empty and <= 150 characters, Value must match regular expression ^[a-zA-Z0-9._-]{1,150}$
Optional. The unique custom id of the live.
type stringrequired
Possible values: [LIVE_TYPE_LIVE, LIVE_TYPE_SIMULIVE]
Required. Immutable. Indicates the type of the live.
source object
Optional. Required if type is LIVE_TYPE_SIMULIVE. Specify the pre-recorded video source for the live.
type string
Possible values: [LIVE_SOURCE_TYPE_LIBRARY]
Required. Indicates the simulive type to choices.
library object
Input only. Required if type is LIVE_SOURCE_TYPE_LIBRARY. Specify the video srouce from library.
id stringrequired
Required. The video library id as the source of the simulive.
name string
Output only. The video library name.
broadcast_mode stringrequired
Possible values: [BROADCAST_MODE_TRADITIONAL_LIVE, BROADCAST_MODE_PLAYBACK, BROADCAST_MODE_DVR]
Required. Immutable. Indicates the broadcast mode of the live.
scheduled_at date-time
Optional. Only used when type is LIVE_TYPE_SIMULIVE. The live will start at the scheduled time if it is set. Otherwise, start immediately.
resolution - LIVE_RESOLUTION_HD: 720p resolution (1280 * 720 pixels) - LIVE_RESOLUTION_FHD: 1080p resolution (1920 * 1080 pixels) - LIVE_RESOLUTION_4K: 4K resolution (3840 * 2160 pixels) (string)required
Possible values: [LIVE_RESOLUTION_HD, LIVE_RESOLUTION_FHD, LIVE_RESOLUTION_4K]
Required. Immutable. Required if broadcast_mode is not BROADCAST_MODE_PLAYBACK.
live_vod object
Optional. Indicates recording the live event after the live ended if it is set.
source stringrequired
Possible values: [LIVE_VOD_SOURCE_CATCHUP, LIVE_VOD_SOURCE_REPLACE, LIVE_VOD_SOURCE_PLAYBACK]
Required. Indicates the VOD source type. It must be LIVE_VOD_SOURCE_PLAYBACK when broadcast_mode of the live is BROADCAST_MODE_PLAYBACK.
replace object
Optional. Required if source is LIVE_VOD_SOURCE_REPLACE.
id stringrequired
Required. The unique id of the VOD.
name string
Output only. The name of the VOD.
playback object
Optional. Required if source is LIVE_VOD_SOURCE_PLAYBACK.
id stringrequired
Required. The unique id of the VOD.
name string
Output only. The name of the VOD.
started_at date-timerequired
Required. The VOD will available after the start time.
ended_at date-timerequired
Required. The VOD will not available after the end time.
security objectrequired
Required. The security settings for the live.
privacy objectrequired
Required. Specify the content visibility.
type stringrequired
Possible values: [SECURITY_PRIVACY_TYPE_PUBLIC, SECURITY_PRIVACY_TYPE_TOKEN]
Required. Indicates the security privacy type.
token object
Optional. Required if type is SECURITY_PRIVACY_TYPE_TOKEN.
device_limit int32
Optional. The limit of the concurrent devices for a token or a redeem code. Default: 0 (Unlimited). Maximum: 1000.
watermark object
Optional. Add watermarks to the player when playing the content, it's not supported for AOD.
enabled booleanrequired
Required. Enable watermark.
type stringrequired
Possible values: [WATERMARK_TYPE_IMAGE, WATERMARK_TYPE_USER_ID]
Required. Indicates the type of watermark.
position stringrequired
Possible values: [WATERMARK_POSITION_BOTTOM_RIGHT, WATERMARK_POSITION_BOTTOM_MIDDLE, WATERMARK_POSITION_BOTTOM_LEFT, WATERMARK_POSITION_CENTER_RIGHT, WATERMARK_POSITION_CENTER_LEFT, WATERMARK_POSITION_TOP_RIGHT, WATERMARK_POSITION_TOP_MIDDLE, WATERMARK_POSITION_TOP_LEFT, WATERMARK_POSITION_RANDOM, WATERMARK_POSITION_CUSTOM]
Required. The position of the watermark.
image object
Optional. Required if type is WATERMARK_TYPE_IMAGE.
library_id stringrequired
Required. The library id of the image.
url string
Output only. The URL of the image.
name string
Output only. The Name of the image.
size floatrequired
Required. The size of the watermark. The range of values that can be set is from 1 to 50.
offset object
Optional. Required if type is WATERMARK_POSITION_CUSTOM.
x int32required
Required. The x-axis position of the watermark. Represented as a percentage of the image width. The range of values that can be set is from 1 to 100.
y int32required
Required. The y-axis position of the watermark. Represented as a percentage of the image height. The range of values that can be set is from 1 to 100.
domain_control object
Optional. Specify the domains that will be allowed to embed the iframe.
enabled boolean
Optional. Enable domain control.
domains string[]
Optional. The list of domains that will be allowed to embed the iframe.
protection object
Optional. Immutable. The content encryption.
type Optional. Indicates the type of protection (string)
Possible values: [PROTECTION_TYPE_DRM]
• PROTECTION_TYPE_DRM: The content will protected by DRM.
geo_control string[]
Immutable. Specify the alpha-2 codes (See: https://www.iban.com/country-codes) to restrict access to the content by geo locations. Allow all regions when empty.
ull_enabled boolean
Optional. Enable ultra-low-latency streaming.
cover_images object
Optional. Customize the cover images on the player.
ready_to_start object
Input only. The cover image when the live is ready to start.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
preview object
Input only. The cover image when the live is previewing.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
player_pause object
Input only. The cover image when the player is paused.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
signal_interruption object
Input only. The cover image when the signal is interrupted.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
end object
Input only. The cover image when the live is ended.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
close object
Input only. The cover image when the live is closed.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
current object
Output only. The current cover image for playback.
type stringrequired
Possible values: [COVER_IMAGE_TYPE_AUTO, COVER_IMAGE_TYPE_CUSTOMIZE]
Required. Indicates the cover image type.
auto object
Output only. Indicates the cover images which are generated automatically. It will be empty which represents the black screen when the content type is live.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
customize object
Optional. Required if type is COVER_IMAGE_TYPE_CUSTOMIZE.
library_id stringrequired
Required. The library id of the cover image.
url string
Output only. The URL of the cover image.
name string
Output only. The name of the cover image.
size int64
Output only. The size of the cover image.
updated_at date-time
Output only. The timestamp of the cover image that was updated.
metadata object
Optional. The metadata of the live.
short_description string
The short description of the resource.
long_description string
The long description of the resource.
labels object[]
Optional. The labels of the resource. The maximum length of labels is 20.
Array [
name stringrequired
Required. The label name. The maximum length of the name is 20.
]
showroom object
Optional. Customize the preferences on showroom.
model object
Optional. The model of showroom preferences.
libraries object[]
Optional. The library assets that is used by the model.
Array [
id stringrequired
Required. The library id of the asset.
name string
Output only. The library name of the asset.
url string
Output only. The URL of the asset.
]
interaction object
Optional. Indicates the interaction settings.
poll_enabled boolean
Optional. Indicates the poll is enabled or not.
chatroom object
Optional. Indicates the chatroom settings.
live object
enabled boolean
Optional. This field indicating the chatroom is enabled or not.
theme string
Possible values: [CHATROOM_THEME_LIGHT, CHATROOM_THEME_DARK]
Optional. Required when enabled = true.
vod object
enabled boolean
Optional. This field indicating the chatroom is enabled or not.
theme string
Possible values: [CHATROOM_THEME_LIGHT, CHATROOM_THEME_DARK]
Optional. Required when enabled = true.
options object
Optional. Indicates the chatroom options.
custom_counter_keys string[]
Optional. Immutable. Indicates the keys of custom counter.
message_ttl string
Optional. Immutable. The maximum time to reserve the chatroom messages. Default: "3600s". Min: "0s". Max: "1209600s".
message_batch_window string
Optional. Immutable. The batch window for the chatroom messages. Default: "3s". Min: "0.5s". Max: "60s".
broadcast_setting object
Optional. Indicates the setting that will broadcast the additional information to the chatroom.
viewer_metrics_enabled boolean
Optional. Immutable. Indicates whether to broadcast the viewer metrics (e.g. the count of concurrent viewers and total viewers).
event_id string
Deprecated. Use chat_id instead. Output only. Empty if poll and chatroom are disabled.
chat_id string
Output only. Empty if chatroom are disabled.
setup object
Output only. The setup for live streaming.
rtmp object
Output only. The setup for RTMP live streaming. It is only available when ingest_types contains LIVE_STREAM_INGEST_TYPE_RTMP.
links object[]
Output only. The RTMP links.
Array [
url string
Output only. The RTMP server endpoint.
pipeline string
Possible values: [LIVE_STREAM_PIPELINE_MAIN, LIVE_STREAM_PIPELINE_BACKUP]
Output only. The live streaming pipeline.
stream_key string
Output only. The key for live streaming.
]
whip object
Output only. The setup for WHIP live streaming. It is only available when ingest_types contains LIVE_STREAM_INGEST_TYPE_WHIP.
links object[]
Output only. The WHIP links.
Array [
url string
Output only. The WHIP server endpoint.
pipeline string
Possible values: [LIVE_STREAM_PIPELINE_MAIN, LIVE_STREAM_PIPELINE_BACKUP]
Output only. The live streaming pipeline.
token string
Output only. The access token for WHIP live streaming.
]
stream object[]
Output only. The streaming information for playback.
Array [
manifests object[]
Indicates the manifest resources.
Array [
protocol - PROTOCOL_HLS: HTTP Live Streaming - PROTOCOL_DASH: Dynamic Adaptive Streaming over HTTP - PROTOCOL_WHEP: WebRTC-HTTP Egress Protocol - PROTOCOL_PROGRESSIVE: Progressive download (string)
Possible values: [PROTOCOL_HLS, PROTOCOL_DASH, PROTOCOL_WHEP, PROTOCOL_PROGRESSIVE]
Indicates the streaming protocol of manifest.
uris object[]
Indicates the uri array of manifest.
Array [
resolutions object[]
The resolution of the manifest.
Array [
height int64
The video resolution height.
width int64
The video resolution width.
]
uri string
The streaming uri of the manifest.
]
]
thumbnail object
Indicates the thumbnail resource.
uri string
Thumbnail seeking uri.
]
labels object[]
Output only. The labels of the live.
Array [
name stringrequired
Required. The label name. The maximum length of the name is 20.
]
created_at date-time
Output only. The timestamp of the live that was created.
updated_at date-time
Output only. The timestamp of the live that was updated.
status string
Possible values: [LIVE_STATUS_PREPARING, LIVE_STATUS_SCHEDULED, LIVE_STATUS_WAIT_FOR_PREVIEW, LIVE_STATUS_INITIATING, LIVE_STATUS_PREVIEW, LIVE_STATUS_LIVE, LIVE_STATUS_LIVE_END, LIVE_STATUS_ENCODING, LIVE_STATUS_VOD_READY, LIVE_STATUS_VOD, LIVE_STATUS_CLOSED, LIVE_STATUS_CANCELING, LIVE_STATUS_ARCHIVING, LIVE_STATUS_ARCHIVED, LIVE_STATUS_FAIL_TO_CREATE, LIVE_STATUS_FAIL_TO_PREVIEW, LIVE_STATUS_FAIL_TO_END, LIVE_STATUS_FAIL_TO_VOD, LIVE_STATUS_FAIL_TO_CANCEL, LIVE_STATUS_FAIL_TO_ARCHIVE]
Output only. The status of the live.
started_time date-time
Output only. The timestamp of the live that was started.
ended_time date-time
Output only. The timestamp of the live that was ended.
save_for_download_enabled boolean
Optional. Enable live recording for download.
ingest_types string[]
Possible values: [LIVE_STREAM_INGEST_TYPE_RTMP]
Optional. Immutable. The types for ingesting live streaming. Default: ['LIVE_STREAM_INGEST_TYPE_RTMP'] Notice: Multiple ingest types are not supported yet.
byo_cdn object
Optional. The setting of bring-your-own cdn.
enabled boolean
Optional. Enable BYO(Bring-your-own) CDN or not.
byo_cdn_setting_id string
Optional. The id of BYO CDN host that you set in the general settings, it's necessary when byo cdn is enabled.
configs object[]
Output only. The preconfigured BYO CDN configurations for AWS distribution.
Array [
type Required. The type of cdn configuration (string)
Possible values: [CDN_CONFIG_TYPE_LIVE_HLS, CDN_CONFIG_TYPE_LIVE_DASH, CDN_CONFIG_TYPE_VOD]
origin Required. The origin user need to set in the distribution (string)
cache_behavior_prefix Required. The cache behavior prefix user need to set in the distribution (string)
]
player_setting object
Output Only. Customize the preferences on player.
setting object
Output Only. The model of player preferences.
id string
Output only. The resource identifier of player setting.
name string
Output only. The name of player setting.
description string
Output Only. The decription of player setting.
libraries object[]
Output Only. The library assets that are used in the setting.
Array [
id string
Output Only. The library id of the asset.
name string
Output only. The library name of the asset.
url string
Output only. The URL of the asset.
]
player object
Input only. Customize the preferences on player setting id.
player_setting_id string
org_id string
Output only. The organization id that the live belongs to.
stream_id string
Optional. Output only. The stream id created from Platform API, which is responsible for providing basic streaming functions like streaming server, content delivery, ...etc, for the live.
on_demand boolean
Output only. Indicates the live is on-demand or not. It usually takes more time until live is ready to start when true.
remux_only boolean
Immutable. Indicates whether the live stream is remuxed without transcoded. Only support LL-HLS output. The following options are restricted:
• type MUST be LIVE_TYPE_LIVE.
• broadcast_mode MUST be BROADCAST_MODE_TRADITIONAL_LIVE.
• live_vod MUST be null.
• ull_enabled MUST be true.
• save_for_download_enabled MUST be false.
relay_settings object[]
Optional. Relay settings for the live. It is used to relay the live stream to other platforms. It only supports when ull_enabled is true.
Array [
type stringrequired
Possible values: [RELAY_TYPE_RTMP]
Required. The relay type, which indicates the destination platform.
display_name string
Optional. The display name for this relay configuration.
is_enabled boolean
Optional. Indicates whether the relay configuration is enabled.
rtmp object
Optional. The RTMP relay information, it is required when type is RELAY_TYPE_RTMP.
url string
The rtmp url of the relay.
stream_key string
The stream key of the relay.
]
error_infos object[]
Output only. Optional. A list of messages that carry the error infos when live is failed.
Array [
reason string
The reason of the error. This is a constant value that identifies the proximate cause of the error. Error reasons are unique within a particular domain of errors. This should be at most 63 characters and match a regular expression of [A-Z][A-Z0-9_]+[A-Z0-9], which represents UPPER_SNAKE_CASE.
domain string
The logical grouping to which the "reason" belongs. The error domain is typically the registered service name of the tool or product that generates the error. Example: "pubsub.googleapis.com". If the error is generated by some common infrastructure, the error domain must be a globally unique value that identifies the infrastructure. For Google API infrastructure, the error domain is "googleapis.com".
metadata object
Additional structured details about this error.
Keys should match /[a-zA-Z0-9-_]/ and be limited to 64 characters in length. When identifying the current value of an exceeded limit, the units should be contained in the key, not the value. For example, rather than {"instanceLimit": "100/request"}, should be returned as, {"instanceLimitPerRequest": "100"}, if the client exceeds the number of instances that can be created in a single (batch) request.
property name* string
]

Example (from schema)

{
  "live": {
    "broadcast_mode": "BROADCAST_MODE_TRADITIONAL_LIVE",
    "cover_images": {
      "close": null,
      "current": null,
      "end": null,
      "player_pause": null,
      "preview": null,
      "ready_to_start": null,
      "signal_interruption": null
    },
    "created_at": "2023-05-31T06:53:43Z",
    "error_infos": [],
    "id": "860d49b8-2ca8-4030-b5ff-f6ec3a1c6196",
    "ingest_types": [
      "LIVE_STREAM_INGEST_TYPE_RTMP"
    ],
    "interaction": {
      "chatroom": {
        "live": {
          "enabled": false,
          "theme": "CHATROOM_THEME_UNSPECIFIED"
        },
        "vod": {
          "enabled": false,
          "theme": "CHATROOM_THEME_UNSPECIFIED"
        }
      },
      "event_id": "",
      "poll_enabled": false
    },
    "labels": [],
    "name": "Amazing Live",
    "resolution": "LIVE_RESOLUTION_HD",
    "save_for_download_enabled": false,
    "security": {
      "domain_control": {
        "domains": [],
        "enabled": false
      },
      "geo_control": [],
      "privacy": {
        "token": null,
        "type": "SECURITY_PRIVACY_TYPE_PUBLIC"
      },
      "protection": {
        "type": "PROTECTION_TYPE_UNSPECIFIED"
      },
      "watermark": {
        "enabled": false,
        "position": "WATERMARK_POSITION_UNSPECIFIED",
        "type": "WATERMARK_TYPE_UNSPECIFIED"
      }
    },
    "setup": {
      "rtmp": {
        "links": [
          {
            "pipeline": "LIVE_STREAM_PIPELINE_MAIN",
            "url": "rtmp://43.207.253.193:1935/live1/stream"
          },
          {
            "pipeline": "LIVE_STREAM_PIPELINE_BACKUP",
            "url": "rtmp://35.76.157.169:1935/live2/stream"
          }
        ]
      }
    },
    "source": null,
    "status": "LIVE_STATUS_WAIT_FOR_PREVIEW",
    "stream": [
      {
        "manifests": [
          {
            "protocol": "PROTOCOL_HLS",
            "uris": [
              {
                "resolutions": [
                  {
                    "height": "720",
                    "width": "1280"
                  },
                  {
                    "height": "480",
                    "width": "852"
                  },
                  {
                    "height": "360",
                    "width": "640"
                  },
                  {
                    "height": "240",
                    "width": "426"
                  }
                ],
                "uri": "https://dh8gxyds8vhu6.cloudfront.net/out/v1/2c4a1f16173244eea3a6b9ce8bfb510c/index.m3u8"
              }
            ]
          },
          {
            "protocol": "PROTOCOL_DASH",
            "uris": [
              {
                "resolutions": [
                  {
                    "height": "720",
                    "width": "1280"
                  },
                  {
                    "height": "480",
                    "width": "852"
                  },
                  {
                    "height": "360",
                    "width": "640"
                  },
                  {
                    "height": "240",
                    "width": "426"
                  }
                ],
                "uri": "https://dh8gxyds8vhu6.cloudfront.net/out/v1/1854c1bbbb404ae2b2f8aa8f41ba7ede/index.mpd"
              }
            ]
          }
        ],
        "thumbnail": null
      }
    ],
    "type": "LIVE_TYPE_LIVE",
    "ull_enabled": false,
    "updated_at": "2023-05-31T06:55:46Z"
  }
}

400

A bad request response. The code is 3 means got an invalid argument. There are more HTTP status code mappings listed on here and gRPC code on here.

application/json

Schema

Schema

code int32
message string
details object[]
Array [
@type string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:
• If no scheme is provided, https is assumed.
• An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
• Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.
Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

401

A unauthenticated response. The header authorization was missing or unidentified.

application/json

Schema

Schema

code int32
message string
details object[]
Array [
@type string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:
• If no scheme is provided, https is assumed.
• An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
• Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.
Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

403

A forbidden response. It means that the provided authorization did not have enough permission to access the resource or the API.

application/json

Schema

Schema

code int32
message string
details object[]
Array [
@type string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:
• If no scheme is provided, https is assumed.
• An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
• Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.
Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

500

A server error response. There are more HTTP status code mappings listed on here.

application/json

Schema

Schema

code int32
message string
details object[]
Array [
@type string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:
• If no scheme is provided, https is assumed.
• An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
• Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.
Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

default

An unexpected error response.

application/json

Schema

Schema

code int32
message string
details object[]
Array [
@type string
A URL/resource name that uniquely identifies the type of the serialized protocol buffer message. This string must contain at least one "/" character. The last segment of the URL's path must represent the fully qualified name of the type (as in path/google.protobuf.Duration). The name should be in a canonical form (e.g., leading "." is not accepted).
In practice, teams usually precompile into the binary all types that they expect it to use in the context of Any. However, for URLs which use the scheme http, https, or no scheme, one can optionally set up a type server that maps type URLs to message definitions as follows:
• If no scheme is provided, https is assumed.
• An HTTP GET on the URL must yield a [google.protobuf.Type][] value in binary format, or produce an error.
• Applications are allowed to cache lookup results based on the URL, or have them precompiled into a binary to avoid any lookup. Therefore, binary compatibility needs to be preserved on changes to types. (Use versioned type names to manage breaking changes.)
Note: this functionality is not currently available in the official protobuf release, and it is not used for type URLs beginning with type.googleapis.com. As of May 2023, there are no widely used type server implementations and no plans to implement one.
Schemes other than http, https (or the empty scheme) might be used with implementation specific semantics.
]

Example (from schema)

{
  "code": 0,
  "message": "string",
  "details": [
    {
      "@type": "string"
    }
  ]
}

Loading...