API FAQ (Frequently Asked Questions)

FAQ on API Integration and Usage

0. General & Common API

Q. How to check if an API request succeeded or failed

A. Every API response includes a result field. Determine the success of the request based on whether this value is SUCCESS or FAIL. A 5xx response is returned only during system failures.

{
  "result": "SUCCESS",
  "data": { ... }
}

{
  "result": "FAIL",
  "error": {
    "errorType": "NOT_FOUND",
    "message": "Resource not found."
  }
}

Q. Where can I issue an x-api-key?

A. You can issue an API key after logging into the Archisketch dashboard. The issued key must be included in the header of all API requests.

X-API-KEY: {x-api-key}

Make sure to keep your x-api-key secure so that it is not exposed externally.

Q. Are there API request limits?

A. Request limits are enforced per company for each API.

• Write: 30 requests per second or fewer

• Read: 50 requests per second or fewer

If exceeded, a TOO_MANY_REQUEST error will be returned for some requests.

Q. What is the maximum length for String parameters?

A. It varies by field, but most are within 255 characters.

1. Modeling

Q. Which 3D file formats are supported?

A. Files are uploaded in multipart/form-data format when creating a model. Please contact the representative to inquire about supported formats.

Q. How do I check if rendering is complete after creating a model?

A. You can check the status through the renderingStatus field of the Get Modeling API (GET /api/v1/modelings/{id}).

• PENDING: Rendering queued / waiting

• IN_PROGRESS: Rendering in progress

• COMPLETED: Rendering complete (the output will be populated in renderAsset)

• FAILED: Rendering failed

2. Component

Q. Can I create a component without a model?

A. Yes, you can. The modelingId is an optional field. To link a model later, use PATCH /api/v1/components/{id}/modeling.

Q. What is isFinal?

A. isFinal indicates whether the component is a final part that cannot be broken down any further into sub-parts.

• true: Final part (cannot be broken down further)

• false: Assembly part that can contain sub-components (childComponents)

Q. What is a Flat BOM?

A. A BOM (Bill of Materials) is a list of parts that make up a product. A Flat BOM flattens the hierarchical structure, allowing you to retrieve all sub-parts at once. You can fetch this using GET /api/v1/components/{id}/bom.

3. Product

Q. What are product decomposition (decompose) and merging (merge)?

A.

• Decompose: Separates a single product into individual products based on its constituent components.

• Merge: Combines multiple products into a single product. You can group them into an option structure by specifying option keys such as color or size.

Q. What is a product option key (optionKey)?

A. An option key is the criteria used to differentiate product options. For example, if optionKey1 is set to "Color", you can assign values like "Beige" or "Gray" to optionValue1 in each option record. You can use up to 5 option keys.

Q. Can I link multiple components to a single product?

A. Yes, you can. You can pass multiple components as an array in components.records, or add options after creating a product using POST /api/v1/sales/{id}/options.

4. Parametric Component

Q. What is the difference between a general component and a parametric component?

A. A general component is a 3D object with a fixed shape. A parametric component is a dynamic component whose parameters—such as width, height, and color—can be adjusted directly by the user within the Archisketch editor. It is used when dimensions need to be freely customized, such as with custom furniture.

Q. Can a parametric component also be registered as a product (Sale)?

A. Yes, it can. Just like general components, parametric components can be registered as products. You can simply use the parametric component ID in components.records when making a POST /api/v1/sales request.