API overview

Alpha3D API is designed to enable partner applications to access account data and assets directly from the Alpha3D application via HTTPS queries. With our API, partner applications can seamlessly retrieve data and 3D assets, and easily integrate them into their own applications.

To start using the Alpha3D API, please reach out to us via info@alpha3d.io to request access. We will work with you to enable API usage for your application and provide any necessary resources to ensure a smooth integration.

Currently, our API is offering four endpoints that partner applications can use to retrieve information from our system:

1. Logging in
2. Querying products
3. Querying 3D models
4. Generate 3D models

The log in endpoint is to enable partner application’s users to log in to their Alpha3D account, which is a prerequisite to retrieve 3D assets information from Alpha3D. The products endpoint should be used if users want to retrieve product information that has been accepted by the user in Alpha3D. Finally, the partner application can do a query to retrieve the 3D asset information together with the file(s).

Alpha3D provides the endpoints, while partner applications have the flexibility to develop their own business processes around these endpoints to best meet their specific needs. See the example process flow below:

When a user opens the Alpha3D integration in the partner application, then the partner application redirects to Alpha3D and displays the log in form to the user. The user has a choice to log in either using their credentials or using their Google account. When they choose to log in with their credentials, partner application makes a query to log the user in. If successful, then Alpha3D returns
a Bearer token which holds the user’s session information and user is redirected back to the partner application.

After that, the partner application can do another query to retrieve the user’s accepted products from Alpha3D. If there are any products that have a given 3D model file attached to them, then Alpha3D returns the product’s info and thumbnail which are then displayed to the user in the partner application.

User can then choose a product which 3D model file they want to retrieve and use in the partner application. When user has chosen the product, partner application will do a query to Alpha3D. When Alpha3D returns the 3D model, the partner application can display the 3D model and user can use the 3D asset in the partner application.

Changes/updates in Alpha3D API

If you need to make a request to our API, please feel free to contact us via info@alpha3d.io. We are always happy to hear from our partners and will carefully review each request. If possible, we will make updates or changes to our API to better meet your needs.

 

 

Authentication

All API calls made to Alpha3D need to be sent over secure HTTPS channel. To access the user’s assets and information, the API calls need to be authenticated with a unique and temporary bearer token that is assigned when user is logged in using the API on the partner application’s side. This token is used to validate if the query is authorized and the user has a valid session.

 

 

Requests

Each request consists of a URL and header parameters. Request can also consist of body parameters and authorization parameters.

The exact request URL format and parameters are described in the specific query description.

 

 

Responses

Each response contains the data from Alpha3D based on the given parameters. In case a query was not executed, the server returns an HTTPS error code together with the error description.

A response format for each query is described in the specific query description.

 

 

Logging in

Description

The goal of this service is to provide a query for partner applications to let users on their side log in to their account in Alpha3D.

 

Request

Method	HTTP request	Description
POST	/alphaar/auth/oauth/token	Logs the user in with the provided credentials.

 

Header parameters

Parameter	Required?	Description
grant_type	Yes	Possible values: “password” “authorization_code” “refresh_token”
refresh_token	No	Bearer token’s refresh token. Is valued only if header parameter grant_type = “refresh_token”
code	No	Single-use code that is replaced with access and refresh token later. Is valued only if header parameter grant_type = “authorization_code”

 

Authorization

Parameter	Required?	Description
Username	Yes	Is given by Alpha3D
Password	No	NULL

 

Body parameters

NB! Only valued if header parameter grant_type = “password”

Parameter	Type	Required?	Description
email	string	Yes	User’s email
password	string	Yes	User’s password

 

Output

	HTTP response code	Return content
1	400	Error messages: “Unsupported grant_type”
2	401	Error messages: “Incorrect email or password”
3	200	Return structure: Parameter Explanation access_token Access token to access Alpha3D externally token_type “bearer” refresh_token Refresh token to refresh log in session expires_in Access token expiration time scope “external” sub User’s email to whom the session belongs to roles User’s role in Alpha3D company Company of the user who logged in uuid User’s UUID email User’s email who logged in jti Unique identifier

 

 

Querying products

Description

The goal of this service is to provide a query for partner applications to retrieve all logged in user’s approved products that have a provided 3D asset file format.

 

Request

Method	HTTP request	Description
GET	/alphaar/api/ext/pr oduct/approved	Returns user’s approved products that have a provided 3D asset file format

 

Input

Parameter	Type	Required?	Description
bearerToken	string	Yes	User’s bearer token from the Login service
fileFormat	string	Yes	3D model file format that the user wants to query the products for. Accepted values: GLB GLTF USD

 

Output

	HTTP response code	Return content
1	401	Error messages: “Invalid token”
2	400	Error messages: “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.” “Provided 3D asset file format is not supported in Alpha3D”
3	200	Return message (list of products): Parameter Explanation uuid Product’s UUID brandName Product’s brand name modelName Product’s model name thumbnail Thumbnail image content

 

 

Querying 3D models

Description

The goal of this service is to provide a query for partner applications to retrieve a 3D asset file for a provided product UUID and file format.

 

Request

Method	HTTP request	Description
GET	/alphaar/api/ext/ass et/{productUuid}	Returns a provided product’s 3D asset file

 

Input

Parameter	Type	Required?	Description
bearerToken	string	Yes	User’s bearer token from the Login service
fileFormat	string	Yes	3D model file format that the user wants query the products. Accepted values: GLB USD GLTF ALL

 

Output

	HTTP response code	Return content
1	401	Error messages: “Invalid token”
2	400	Error messages: “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.” “Provided file format is wrong. Accepted values: “GLB”, “USD”, “GLTF” or “ALL”” “Product with provided UUID does not exist or is not accepted.”
3	200	Return message (list of files): Parameter Explanation attachmentUuid Attachment’s UUID fileName File’s name fileType File type base64 File content extension File extention. Possible values: glb gltf usd

 

 

Generate 3D models

Description

This service’s goal is to provide a query for partner applications to generate a 3D asset file for a provided project name, category, product name, and image.

 

Request

Method	HTTP request	Description
POST	/alphaar/api/ext/project	Returns a response message

 

Input

Parameter	Type	Required?	Description
bearerToken	string	Yes	User’s bearer token from the Login service
ProjectName	string	No	Provided name for the project. If empty then generated automatically using the same logic as in the system (“Project ”).
projectCategory	string	Yes	Accepted values: ANYTHING SOFA SNEAKERS
productName	string	Yes	Product model name. For “ANYTHING” category, this is the text describing the 3D model that user wants to generate.
imageType	string(JPG,JPEG,PNG,WEBP)	Yes/No	Mandatory when projectCategory is “SOFA” or “SNEAKERS”.
image	base64	Yes/No	Mandatory when projectCategory is “SOFA” or “SNEAKERS”.

 

Output

	HTTP response code	Return content
1	401	Error messages: “Invalid token”
2	400	Error messages: “Alpha3D is restricted due to an unpaid invoice. Please visit Alpha3D for more information.” “One or many required request parameters are missing or not correct”
3	200	Generated project UUID