From e86ed4fbacd5c734a48eaad6b03594ad7835389e Mon Sep 17 00:00:00 2001 From: claudi Date: Tue, 7 Apr 2026 09:50:59 +0200 Subject: [PATCH] added media api yaml for future enhancement --- commerce_media_v1_beta_oas3.yaml | 1350 ++++++++++++++++++++++++++++++ 1 file changed, 1350 insertions(+) create mode 100644 commerce_media_v1_beta_oas3.yaml diff --git a/commerce_media_v1_beta_oas3.yaml b/commerce_media_v1_beta_oas3.yaml new file mode 100644 index 0000000..fdc4e69 --- /dev/null +++ b/commerce_media_v1_beta_oas3.yaml @@ -0,0 +1,1350 @@ +--- +openapi: "3.0.0" +info: + title: "Media API" + description: "The Media API lets sellers to create, upload, and retrieve\ + \ files, including:" + contact: + name: "eBay Inc," + license: + name: "eBay API License Agreement" + url: "https://developer.ebay.com/join/api-license-agreement" + version: "v1_beta.4.2" +servers: +- url: "https://apim.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" +- url: "https://api.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" +paths: + /image/create_image_from_file: + post: + tags: + - "image" + description: "This method uploads a picture file to eBay Picture Services (EPS)\ + \ using multipart/form-data.

All images must comply with eBay's picture\ + \ requirements, such as dimension and file size restrictions. For more information,\ + \ see Picture policy. The image formats supported are JPG,\ + \ GIF, PNG, BMP, TIFF, AVIF, HEIC,\ + \ and WEBP. For more information, see Image requirements.

Note: Animated GIF, and multi-page PNG/TIFF files, are not\ + \ supported. Any animation effect of supported formats will be lost upon upload.

This\ + \ call does not have a JSON Request payload but uploads the file as form-data.\ + \ For example:

 image: "sample_picture.jpg"
See\ + \ Samples for information.

Note:\ + \ You must use a Content-Type header with its value set to 'multipart/form-data'.

When\ + \ an EPS image is successfully created, the method returns the HTTP Status\ + \ Code 201 Created. The method also returns the getImage URI\ + \ in the Location response header.

Important! Make sure to capture the\ + \ image ID URI returned in the response location header provided in the following format:

https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}\ + \

You can capture the entire URI, or just save the {image_id}\ + \ only. Pass the {image_id} as a path parameter in the getImage method to return the value needed to associate an\ + \ image to a listing using the Trading and Inventory APIs.

See\ + \ Managing images for additional details.


Important!All\ + \ POST methods in the Media API, including this method, are subject to short-duration\ + \ rate limits at the user level: 50 requests per 5 seconds.

" + operationId: "createImageFromFile" + parameters: + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to multipart/form-data.\ + \

For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + responses: + "201": + description: "Created" + headers: + Location: + schema: + type: "string" + description: "The location response header contains the URI of the\ + \ newly created image ID in the format:
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}\ + \

Capture this URI to use with the getImage method. See Managing images for more information." + content: + application/json: + schema: + $ref: "#/components/schemas/ImageResponse" + "400": + description: "Bad Request" + x-response-codes: + errors: + 190202: + domain: "API_MEDIA" + category: "REQUEST" + description: "The supplied image dimensions exceed the limit. Please\ + \ refer to the documentation." + 190203: + domain: "API_MEDIA" + category: "REQUEST" + description: "The supplied image is in a format that is not supported.\ + \ Please refer to the documentation for a list of supported formats." + 190201: + domain: "API_MEDIA" + category: "REQUEST" + description: "The image file size is larger than the limit. Please\ + \ refer to the documentation." + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /image/create_image_from_url: + post: + tags: + - "image" + description: "This method uploads a picture to eBay Picture Services (EPS) from\ + \ the specified URL. Specify the location of the picture on an external web\ + \ server through the imageUrl field.

All images must comply with\ + \ eBay’s picture requirements, such as dimension and file size restrictions.\ + \ For more information, see Picture policy. The image formats supported are JPG,\ + \ GIF, PNG, BMP, TIFF, AVIF, HEIC,\ + \ and WEBP. In addition, the provided URL must be secured using HTTPS\ + \ (HTTP is not permitted). For more information, see Image requirements.

Note: Animated GIF, and multi-page PNG/TIFF files, are not\ + \ supported. Any animation effect of supported formats will be lost upon upload.

When\ + \ an EPS image is successfully created, the method returns the HTTP Status\ + \ Code 201 Created. The method also returns the getImage URI\ + \ in the Location response header.

Important! Make sure to capture the\ + \ image ID URI returned in the response location header provided in the following format:

https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}\ + \

You can capture the entire URI, or just save the {image_id}\ + \ only. Pass the {image_id} as a path parameter in the getImage method to return the value needed to associate an\ + \ image to a listing using the Trading and Inventory APIs.

See\ + \ Managing images for additional details.


Important!All\ + \ POST methods in the Media API, including this method, are subject to short-duration\ + \ rate limits at the user level: 50 requests per 5 seconds.

" + operationId: "createImageFromUrl" + parameters: + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to application/json.

\ + \ For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateImageFromUrlRequest" + required: true + responses: + "201": + description: "Created" + headers: + Location: + schema: + type: "string" + description: "The location response header contains the URI of the\ + \ newly created image ID in the format:
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}\ + \

Capture this URI to use with the getImage method. See Managing images for more information." + content: + application/json: + schema: + $ref: "#/components/schemas/ImageResponse" + "400": + description: "Bad Request" + x-response-codes: + errors: + 190202: + domain: "API_MEDIA" + category: "REQUEST" + description: "The supplied image dimensions exceed the limit. Please\ + \ refer to the documentation." + 190203: + domain: "API_MEDIA" + category: "REQUEST" + description: "The supplied image is in a format that is not supported.\ + \ Please refer to the documentation for a list of supported formats." + 190201: + domain: "API_MEDIA" + category: "REQUEST" + description: "The image file size is larger than the limit. Please\ + \ refer to the documentation." + 190204: + domain: "API_MEDIA" + category: "REQUEST" + description: "No valid image can be downloaded from the provided imageUrl.\ + \ Please refer to the documentation." + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /image/{image_id}: + get: + tags: + - "image" + description: "This method retrieves an EPS image URL and its expiration details\ + \ for the unique identifier specified in the path parameter image_id.\ + \ Use the retrieved EPS image URL to add the image to a listing through the\ + \ Inventory API or the Trading API. See Managing images for additional details.

Note: If a user inputs a valid image_id\ + \ as a path parameter but the EPS image associated with that ID has expired,\ + \ the call will fail and a 404 Not Found status code will be returned." + operationId: "getImage" + parameters: + - name: "image_id" + in: "path" + description: "This path parameter is the unique identifier of a created image.\ + \ Use the value returned in the location header of the method used to create\ + \ the image (createImageFromFile or createImageFromUrl, as\ + \ applicable)." + required: true + schema: + type: "string" + responses: + "200": + description: "OK" + content: + application/json: + schema: + $ref: "#/components/schemas/ImageResponse" + "400": + description: "Bad Request" + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + "404": + description: "Not Found" + x-response-codes: + errors: + 190200: + domain: "API_MEDIA" + category: "REQUEST" + description: "The image resource was not found." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /video: + post: + tags: + - "video" + description: "This method creates a video resource. When using this method,\ + \ specify the title, size, and classification of the\ + \ video resource to be created. Description is an optional field for\ + \ this method.

Tip: See Adding a video to your listing in the eBay Seller\ + \ Center for details about video formatting requirements and restrictions,\ + \ or visit the relevant eBay site help pages for the region in which the listings\ + \ will be posted.

When a video resource is successfully\ + \ created, the method returns the HTTP Status Code 201 Created.The\ + \ method also returns the location response header containing the video\ + \ ID, which you can use to retrieve the video.

Note: There\ + \ is no ability to edit metadata on videos at this time. There is also no\ + \ method to delete videos.
To upload a created video to a created\ + \ video resource, use the uploadVideo method.

Important!All POST methods in the\ + \ Media API, including this method, are subject to short-duration rate limits\ + \ at the user level: 50 requests per 5 seconds.

" + operationId: "createVideo" + parameters: + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to application/json.

\ + \ For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateVideoRequest" + required: false + responses: + "201": + description: "Created" + headers: + Location: + schema: + type: "string" + description: "The created video resource location and the unique video\ + \ ID." + "400": + description: "Bad Request" + x-response-codes: + errors: + 190002: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid size. Size (in bytes) is required." + 190003: + domain: "API_MEDIA" + category: "REQUEST" + description: "Maximum size exceeded for supported uploads. Please\ + \ refer to documentation." + 190016: + domain: "API_MEDIA" + category: "REQUEST" + description: "Markups are not permitted in the video title." + 190017: + domain: "API_MEDIA" + category: "REQUEST" + description: "Markups are not permitted in the video description." + 190006: + domain: "API_MEDIA" + category: "REQUEST" + description: "Title is required." + 190004: + domain: "API_MEDIA" + category: "REQUEST" + description: "Title length exceeded. Please refer to documentation." + 190005: + domain: "API_MEDIA" + category: "REQUEST" + description: "Description length exceeded. Please refer to documentation." + 190014: + domain: "API_MEDIA" + category: "REQUEST" + description: "A video classification is required." + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /video/{video_id}: + get: + tags: + - "video" + description: "This method retrieves a video's metadata and content given a specified\ + \ video ID. The method returns the title, size, classification,\ + \ description, video ID, playList, status, status\ + \ message (if any), expiration date, and thumbnail image\ + \ of the retrieved video.

The video's title, size, classification,\ + \ and description are set using the createVideo method.

The video's playList\ + \ contains two URLs that link to instances of the streaming video based on\ + \ the supported protocol.

The status field contains the current\ + \ status of the video. After a video upload is successfully completed, the\ + \ video's status will show as PROCESSING until the video\ + \ reaches one of the terminal states of LIVE, BLOCKED\ + \ or PROCESSING_FAILED.

If a video's processing fails, it\ + \ could be because the file is corrupted, is too large, or its size doesn't\ + \ match what was provided in the metadata. Refer to the error messages to\ + \ determine the cause of the video's failure to upload.

The status\ + \ message will indicate why a video was blocked from uploading.

If\ + \ a video is not being used on an active listing, its expiration date\ + \ is automatically set to 30 days after the video's initial upload.

The\ + \ video's thumbnail image is automatically generated when the video\ + \ is created." + operationId: "getVideo" + parameters: + - name: "video_id" + in: "path" + description: "The unique identifier of the video to be retrieved." + required: true + schema: + type: "string" + responses: + "200": + description: "OK" + content: + application/json: + schema: + $ref: "#/components/schemas/Video" + "400": + description: "Bad Request" + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + "404": + description: "Not Found" + x-response-codes: + errors: + 190001: + domain: "API_MEDIA" + category: "REQUEST" + description: "The specified video_Id does not exist." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /video/{video_id}/upload: + post: + tags: + - "video" + description: "This method associates the specified file with the specified video\ + \ ID and uploads the input file. After the file has been uploaded the\ + \ processing of the file begins.

Note: The size of the video\ + \ to be uploaded must exactly match the size of the video's input stream that\ + \ was set in the createVideo method. If the sizes do not match, the\ + \ video will not upload successfully.

When a video is successfully\ + \ uploaded, it returns the HTTP Status Code 200 OK.
The status flow is PENDING_UPLOAD > PROCESSING\ + \ > LIVE, PROCESSING_FAILED, or BLOCKED.\ + \ After a video upload is successfully completed, the status will show as\ + \ PROCESSING until the video reaches one of the terminal states\ + \ of LIVE, BLOCKED, or PROCESSING_FAILED.\ + \ If the size information (in bytes) provided is incorrect, the API will throw\ + \ an error.

Tip: See Adding a video to your listing in the eBay Seller\ + \ Center for details about video formatting requirements and restrictions,\ + \ or visit the relevant eBay site help pages for the region in which the listings\ + \ will be posted.

To retrieve an uploaded video, use the\ + \ getVideo method.

Important!All POST methods in the\ + \ Media API, including this method, are subject to short-duration rate limits\ + \ at the user level: 50 requests per 5 seconds.

" + operationId: "uploadVideo" + parameters: + - name: "Content-Length" + in: "header" + description: "Use this header to specify the content length for the upload.\ + \ Use Content-Range: bytes {1}-{2}/{3} and Content-Length:{4} headers.
Note:\ + \ This header is optional and is only required for resumable uploads\ + \ (when an upload is interrupted and must be resumed from a certain point)." + required: false + schema: + type: "string" + - name: "Content-Range" + in: "header" + description: "Use this header to specify the content range for the upload.\ + \ The Content-Range should be of the following bytes ((?:[0-9]+-[0-9]+)|\\\ + \\\\\\*)/([0-9]+|\\\\\\\\*) pattern.

Note: This header\ + \ is optional and is only required for resumable uploads (when an\ + \ upload is interrupted and must be resumed from a certain point)." + required: false + schema: + type: "string" + - name: "Content-Type" + in: "header" + description: "Use this header to specify the content type for the upload.\ + \ The Content-Type should be set to application/octet-stream." + required: true + schema: + type: "string" + - name: "video_id" + in: "path" + description: "The unique identifier of the video to be uploaded." + required: true + schema: + type: "string" + requestBody: + description: "The request payload for this method is the input stream for\ + \ the video source. The input source must be an .mp4 file of the type MPEG-4\ + \ Part 10 or Advanced Video Coding (MPEG-4 AVC)." + content: + application/octet-stream: + schema: + description: "The request payload for this method is the input stream\ + \ for the video source. The input source must be an .mp4 file of the\ + \ type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4 AVC)." + $ref: "#/components/schemas/InputStream" + required: false + responses: + "200": + description: "OK" + "400": + description: "Bad Request" + x-response-codes: + errors: + 190007: + domain: "API_MEDIA" + category: "REQUEST" + description: "The content length does not match the content size specified." + 190010: + domain: "API_MEDIA" + category: "REQUEST" + description: "The video's Content-Range is invalid. The Content-Range\ + \ should be of the following bytes ((?:[0-9]+-[0-9]+)|\\\\\\\\*)/([0-9]+|\\\ + \\\\\\*) pattern." + 190015: + domain: "API_MEDIA" + category: "REQUEST" + description: "The uploaded content must match the video size." + 190012: + domain: "API_MEDIA" + category: "REQUEST" + description: "The content length of the video is invalid." + "411": + description: "Content Length Required" + x-response-codes: + errors: + 190008: + domain: "API_MEDIA" + category: "REQUEST" + description: "The content length is required." + "500": + description: "Internal Server Error" + x-response-codes: + errors: + 190000: + domain: "API_MEDIA" + category: "APPLICATION" + description: "There was a problem with an eBay internal system or\ + \ process. Contact eBay developer support for assistance." + "403": + description: "Forbidden" + x-response-codes: + errors: + 190013: + domain: "API_MEDIA" + category: "REQUEST" + description: "Unauthorized access." + "404": + description: "Not Found" + x-response-codes: + errors: + 190001: + domain: "API_MEDIA" + category: "REQUEST" + description: "The specified video_Id does not exist." + "416": + description: "Range Not Satisfiable" + x-response-codes: + errors: + 190009: + domain: "API_MEDIA" + category: "REQUEST" + description: "The Content-Range specified is incorrect. Use Content-Range:\ + \ bytes {1}}-{2}/{3} and Content-Length:{4} headers." + "409": + description: "Conflict" + x-response-codes: + errors: + 190011: + domain: "API_MEDIA" + category: "REQUEST" + description: "The video is already uploaded." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + /document: + post: + tags: + - "document" + description: "This method stages a document to be uploaded, and requires the\ + \ type of document to be uploaded, and the language(s) that the document contains.\ + \ A successful call returns a documentId value that is then used as\ + \ a path parameter in an uploadDocument call.

When a document is successfully created, the\ + \ method returns the HTTP Status Code 201 Created. The method\ + \ returns documentId in the response payload, which you can use to\ + \ retrieve the document resource. This ID is also returned in the location\ + \ header, for convenience.

Important! Make sure to capture the\ + \ document ID value returned in the response payload. This value is required\ + \ to use the other methods in the document resource, and also needed\ + \ to associate a document to a listing using the Trading and Inventory APIs.


To\ + \ upload a created document, use the document ID returned from this method's\ + \ response with the uploadDocument method. See Managing documents for information on creating, uploading,\ + \ and adding documents to listings.

Important!All POST methods in the\ + \ Media API, including this method, are subject to short-duration rate limits\ + \ at the user level: 50 requests per 5 seconds.

" + operationId: "createDocument" + parameters: + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to application/json.

\ + \ For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateDocumentRequest" + required: false + responses: + "201": + description: "Created" + headers: + Location: + schema: + type: "string" + description: "The location response header returns the getDocument\ + \ URI." + content: + application/json: + schema: + $ref: "#/components/schemas/CreateDocumentResponse" + "400": + description: "Bad Request" + x-response-codes: + errors: + 190050: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid 'languages' value(s)." + 190051: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid 'documentType' value." + "500": + description: "Internal Server Error" + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + servers: + - url: "https://api.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" + /document/create_document_from_url: + post: + tags: + - "document" + description: "This method downloads a document from the provided URL and adds\ + \ that document to the user's account. This method requires the URL of the\ + \ document, the type of document to be uploaded, and the language(s) that\ + \ the document contains.

When a document is successfully created,\ + \ the method returns the HTTP Status Code 201 Created. The method\ + \ returns documentId in the response payload, which you can use to\ + \ retrieve the document resource. This ID is also returned in the location\ + \ header, for convenience.

Important! Make sure to capture the\ + \ document ID value returned in the response payload. This value is required\ + \ to use the other methods in the document resource, and also needed\ + \ to associate a document to a listing using the Trading and Inventory APIs.


After\ + \ creating a document using this method, a getDocument call should be made to check for a documentStatus\ + \ of ACCEPTED. Only documents with this status can be added to\ + \ a listing. See Managing documents for more information on creating,\ + \ uploading, and adding documents to listings.

Important!All POST methods in the\ + \ Media API, including this method, are subject to short-duration rate limits\ + \ at the user level: 50 requests per 5 seconds.

" + operationId: "createDocumentFromUrl" + parameters: + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to application/json.

\ + \ For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateDocumentFromUrlRequest" + required: false + responses: + "201": + description: "Created" + headers: + Location: + schema: + type: "string" + description: "The location response header returns the getDocument\ + \ URI." + content: + application/json: + schema: + $ref: "#/components/schemas/CreateDocumentResponse" + "400": + description: "Bad Request" + x-response-codes: + errors: + 190050: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid ‘languages’ value(s)." + 190051: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid ‘documentType’ value." + 190055: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid 'documentUrl' value." + 190058: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid 'request'." + 190059: + domain: "API_MEDIA" + category: "REQUEST" + description: "Invalid value for ‘documentUrl’ was supplied. Failed\ + \ to download document from 'documentUrl'." + 190056: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or invalid domain in 'documentUrl'." + 190057: + domain: "API_MEDIA" + category: "REQUEST" + description: "Missing or malformed 'documentUrl'." + 190062: + domain: "API_MEDIA" + category: "REQUEST" + description: "Invalid value for ‘documentUrl’ was supplied. Not an\ + \ allowed file type for download from ‘documentUrl'." + 190063: + domain: "API_MEDIA" + category: "REQUEST" + description: "Invalid value for ‘documentUrl’ was supplied. File size\ + \ exceeds the maximum limit from ‘documentUrl'." + 190060: + domain: "API_MEDIA" + category: "REQUEST" + description: "Invalid value for ‘documentUrl’ was supplied. Please\ + \ provide an HTTPS 'documentUrl'." + 190061: + domain: "API_MEDIA" + category: "REQUEST" + description: "Invalid value for ‘documentUrl’ was supplied. File type\ + \ could not be detected from ‘documentUrl'." + "500": + description: "Internal Server Error" + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + servers: + - url: "https://api.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" + /document/{document_id}: + get: + tags: + - "document" + description: "This method retrieves the current status and metadata of\ + \ the specified document.

Important! The document ID value\ + \ returned in the response payload of the createDocument method is a required input path parameter for this method.

See\ + \ Managing documents for additional information.

" + operationId: "getDocument" + parameters: + - name: "document_id" + in: "path" + description: "The unique identifier of the document for which status and metadata\ + \ is being retrieved.

This value is returned in the response of the\ + \ createDocument method." + required: true + schema: + type: "string" + responses: + "200": + description: "Uploaded" + content: + application/json: + schema: + $ref: "#/components/schemas/DocumentResponse" + "400": + description: "Bad Request" + "500": + description: "Internal Server Error" + "404": + description: "Document Not Found" + x-response-codes: + errors: + 190052: + domain: "API_MEDIA" + category: "REQUEST" + description: "No document found with id {document_id}." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + servers: + - url: "https://api.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" + /document/{document_id}/upload: + post: + tags: + - "document" + description: "This method associates the specified file with the specified document\ + \ ID and uploads the input file. After the file has been uploaded, the processing\ + \ of the file begins. Supported file types include .PDF, .JPEG/.JPG, and .PNG,\ + \ with a maximum file size of 10 MB (10485760 bytes).

Note: Animated and multi-page PNG files are not currently\ + \ supported.
Note: The document ID value returned in the response\ + \ of the createDocument method is a required input path parameter for this method.\ + \ This value is also returned in the location header of the createDocument\ + \ response payload.
A successful upload returns the HTTP Status\ + \ Code 200 OK.

See Managing documents for additional information.

\ + \ Note: You must use a Content-Type\ + \ header with its value set to multipart/form-data.

This\ + \ call does not have a JSON Request payload but uploads the file as form-data.\ + \ For example:
file: @"/C:/Users/.../drone_user_warranty.pdf"
See\ + \ Samples for information.

Important!All POST methods in the\ + \ Media API, including this method, are subject to short-duration rate limits\ + \ at the user level: 50 requests per 5 seconds.

" + operationId: "uploadDocument" + parameters: + - name: "document_id" + in: "path" + description: "The unique identifier of the document to be uploaded.

This\ + \ value is returned in the response of the createDocument method." + required: true + schema: + type: "string" + - name: "Content-Type" + in: "header" + description: "This header indicates the format of the request body provided\ + \ by the client. Its value should be set to multipart/form-data.\ + \

For more information, refer to HTTP request headers." + required: true + schema: + type: "string" + responses: + "200": + description: "Uploaded" + content: + application/json: + schema: + $ref: "#/components/schemas/DocumentResponse" + "400": + description: "Bad Request" + "500": + description: "Internal Server Error" + "404": + description: "Document Not Found" + x-response-codes: + errors: + 190052: + domain: "API_MEDIA" + category: "REQUEST" + description: "No document found with id {document_id}." + security: + - api_auth: + - "https://api.ebay.com/oauth/api_scope/sell.inventory" + servers: + - url: "https://api.ebay.com{basePath}" + description: "Production" + variables: + basePath: + default: "/commerce/media/v1_beta" +components: + schemas: + CreateDocumentFromUrlRequest: + type: "object" + properties: + documentType: + type: "string" + description: "The type of the document being created. For example, a USER_GUIDE_OR_MANUAL\ + \ or a SAFETY_DATA_SHEET. For implementation help, refer\ + \ to eBay\ + \ API documentation" + documentUrl: + type: "string" + description: "The URL of the document being created.

The document\ + \ referenced by the URL must be a .pdf, .png, .jpg, or .jpeg file, and\ + \ must be no larger than 10 MB." + languages: + type: "array" + description: "This array shows the language(s) used in the document." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: "This type contains the metadata used to create the document ID\ + \ when creating a document using a URL." + CreateDocumentRequest: + type: "object" + properties: + documentType: + type: "string" + description: "The type of the document being uploaded. For example, a USER_GUIDE_OR_MANUAL\ + \ or a SAFETY_DATA_SHEET. For implementation help, refer\ + \ to eBay\ + \ API documentation" + languages: + type: "array" + description: "This array shows the language(s) used in the document." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: "This type contains the metadata used to create the document ID." + CreateDocumentResponse: + type: "object" + properties: + documentId: + type: "string" + description: "The unique identifier of the document to be uploaded.

This\ + \ value is returned in the response and location header of the\ + \ createDocument and createDocumentFromUrl methods. This\ + \ ID can be used with the getDocument and uploadDocument\ + \ methods, and to add an uploaded document to a listing. See Adding documents to listings for more information. " + documentStatus: + type: "string" + description: "The status of the document resource.

For example, the\ + \ value PENDING_UPLOAD is the initial state when the reference\ + \ to the document has been created using the createDocument method.\ + \ When creating a document using the createDocumentFromUrl method,\ + \ the initial state will be SUBMITTED. For implementation\ + \ help, refer to eBay\ + \ API documentation" + documentType: + type: "string" + description: "The type of the document uploaded. For example, USER_GUIDE_OR_MANUAL.\ + \ For implementation help, refer to eBay\ + \ API documentation" + languages: + type: "array" + description: "This array shows the language(s) used in the document." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: "This type provides information about the created document ID." + CreateImageFromUrlRequest: + type: "object" + properties: + imageUrl: + type: "string" + description: "The image URL of the self-hosted picture to upload to eBay\ + \ Picture Services (EPS). In addition to the picture requirements in Picture policy, the provided URL must be secured\ + \ using HTTPS (HTTP is not permitted). For more information, see Image requirements." + description: "A type that provides the location of the image." + CreateVideoRequest: + type: "object" + properties: + classification: + type: "array" + description: "The intended use for this video content. Currently, videos\ + \ can only be added and associated with eBay listings, so the only supported\ + \ value is ITEM." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: + type: "string" + description: "The description of the video." + size: + type: "integer" + description: "The size, in bytes, of the video content.

Max:\ + \ 157,286,400 bytes" + format: "int32" + title: + type: "string" + description: "The title of the video." + description: "The request to create a video, which must contain the video's\ + \ title, size, and classification. Description\ + \ is an optional field when creating videos." + DocumentMetadata: + type: "object" + properties: + fileName: + type: "string" + description: "The name of the file including its extension (for example,\ + \ drone_user_warranty.pdf)." + fileSize: + type: "string" + description: "The size, in bytes, of the document content." + fileType: + type: "string" + description: "The type of the file uploaded. Supported file types include\ + \ the following: pdf, jpeg, jpg,\ + \ and png." + description: "This type provides information about the documentId." + DocumentResponse: + type: "object" + properties: + documentId: + type: "string" + description: "The unique ID of the document." + documentMetadata: + description: "This container provides the name, size, and type of the specified\ + \ file." + $ref: "#/components/schemas/DocumentMetadata" + documentStatus: + type: "string" + description: "The status of the document resource.

Once a document\ + \ has been uploaded using the uploadDocument method, the documentStatus\ + \ will be SUBMITTED. The document will then either be accepted\ + \ or rejected. Only documents with the status of ACCEPTED\ + \ are available to be added to a listing. For implementation help, refer\ + \ to eBay\ + \ API documentation" + documentType: + type: "string" + description: "The type of the document uploaded. For example, USER_GUIDE_OR_MANUAL.\ + \ For implementation help, refer to eBay\ + \ API documentation" + languages: + type: "array" + description: "This array shows the language(s) used in the document." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: "This type provides information returned about a created document\ + \ ID, which may or may not have been uploaded." + Error: + type: "object" + properties: + category: + type: "string" + description: "Identifies the type of erro." + domain: + type: "string" + description: "Name for the primary system where the error occurred. This\ + \ is relevant for application errors." + errorId: + type: "integer" + description: "A unique number to identify the error." + format: "int32" + inputRefIds: + type: "array" + description: "An array of request elements most closely associated to the\ + \ error." + items: + type: "string" + longMessage: + type: "string" + description: "A more detailed explanation of the error." + message: + type: "string" + description: "Information on how to correct the problem, in the end user's\ + \ terms and language where applicable." + outputRefIds: + type: "array" + description: "An array of request elements most closely associated to the\ + \ error." + items: + type: "string" + parameters: + type: "array" + description: "An array of name/value pairs that describe details the error\ + \ condition. These are useful when multiple errors are returned." + items: + $ref: "#/components/schemas/ErrorParameter" + subdomain: + type: "string" + description: "Further helps indicate which subsystem the error is coming\ + \ from. System subcategories include: Initialization, Serialization, Security,\ + \ Monitoring, Rate Limiting, etc." + description: "This type defines the fields that can be returned in an error." + ErrorParameter: + type: "object" + properties: + name: + type: "string" + description: "The object of the error." + value: + type: "string" + description: "The value of the object." + Image: + type: "object" + properties: + imageUrl: + type: "string" + description: "The URL of the image's location." + description: "A type that provides the location of the image." + ImageResponse: + type: "object" + properties: + expirationDate: + type: "string" + description: "The date and time when an unused EPS image will expire and\ + \ be removed from the EPS server, in Coordinated Universal Time (UTC).\ + \ As long as an EPS image is being used in an active listing, that image\ + \ will remain on the EPS server and be accessible." + imageUrl: + type: "string" + description: "The EPS URL to access the uploaded image. This URL will be\ + \ used in listing calls to add the image to a listing." + maxDimensionImageUrl: + type: "string" + description: "The EPS URL to access the maximum dimension version of the\ + \ uploaded image." + description: "A type that provides an image's details including its URL and\ + \ expiration." + InputStream: + type: "object" + description: "The streaming input of the video source. The input source must\ + \ be an .mp4 file of the type MPEG-4 Part 10 or Advanced Video Coding (MPEG-4\ + \ AVC)." + Moderation: + type: "object" + properties: + rejectReasons: + type: "array" + description: "The reason(s) why the specified video was blocked by moderators." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: "A container that provides video moderation information when calling\ + \ the getVideo method.

This container is returned\ + \ if the specified video has been blocked by moderators.

Tip:\ + \ See Video moderation and restrictions in the eBay Seller\ + \ Center for details about video moderation." + Play: + type: "object" + properties: + playUrl: + type: "string" + description: "The playable URL for this video." + protocol: + type: "string" + description: "The protocol for the video playlist. Supported protocols are\ + \ DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP\_Live Streaming).\ + \ For implementation help, refer to eBay\ + \ API documentation" + description: "The two streaming video URLs available for a successfully uploaded\ + \ video with a status of LIVE. The supported streaming video\ + \ protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP\_\ + Live Streaming)." + Video: + type: "object" + properties: + classification: + type: "array" + description: "The intended use for this video content. Currently, videos\ + \ can only be added and associated with eBay listings, so the only supported\ + \ value is ITEM." + items: + type: "string" + description: " For implementation help, refer to eBay\ + \ API documentation" + description: + type: "string" + description: "The description of the video. The video description is an\ + \ optional field that can be set using the createVideo method." + expirationDate: + type: "string" + description: "The date and time when an unused video will expire and be\ + \ removed from the eBay Video Services server, in Coordinated Universal\ + \ Time (UTC).

As long as a video is being used in an active listing,\ + \ that video will remain on the server and be accessible. If a video is\ + \ not being used on an active listing, its expiration date is automatically\ + \ set to 30 days after the video's initial upload." + moderation: + description: "The video moderation information that is returned if a video\ + \ is blocked by moderators.

Tip: See Video moderation and restrictions in the eBay\ + \ Seller Center for details about video moderation.

If\ + \ the video status is BLOCKED, ensure that the video complies\ + \ with eBay's video formatting and content guidelines. Afterwards, begin\ + \ the video creation and upload procedure anew using the createVideo\ + \ and uploadVideo methods." + $ref: "#/components/schemas/Moderation" + playLists: + type: "array" + description: "The playlist created for the uploaded video, which provides\ + \ the streaming video URLs to play the video. The supported streaming\ + \ video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and\ + \ HLS (HTTP\_Live Streaming). The playlist will only be generated if a\ + \ video is successfully uploaded with a status of LIVE." + items: + $ref: "#/components/schemas/Play" + size: + type: "integer" + description: "The size, in bytes, of the video content." + format: "int32" + status: + type: "string" + description: "The status of the current video resource. For implementation\ + \ help, refer to eBay\ + \ API documentation" + statusMessage: + type: "string" + description: "The statusMessage field contains additional information\ + \ on the status. For example, information on why processing might have\ + \ failed or if the video was blocked." + thumbnail: + description: "The URL of the thumbnail image of the video. The thumbnail\ + \ image's URL must be an eBayPictureURL (EPS URL)." + $ref: "#/components/schemas/Image" + title: + type: "string" + description: "The title of the video." + videoId: + type: "string" + description: "The unique ID of the video." + description: "A response field that retrieves all the metadata for the video,\ + \ including its title, classification, size, description,\ + \ status, status message (if any), and expiration date." + securitySchemes: + api_auth: + type: "oauth2" + description: "The security definitions for this API. Please check individual\ + \ operations for applicable scopes." + flows: + authorizationCode: + authorizationUrl: "https://auth.ebay.com/oauth2/authorize" + tokenUrl: "https://api.ebay.com/identity/v1/oauth2/token" + scopes: + https://api.ebay.com/oauth/api_scope/sell.inventory: "View and manage\ + \ your inventory and offers"