Getting started

The REST API is the primary mechanism for interacting with xeoServices. It is designed to provide maximum flexibility when integrated with any 3D application or IFC conversion pipeline.

Additionally, xeoServices offers an easy-to-install xeoCLI tool. This tool is useful for ad-hoc tasks such as testing or custom integration within a closed environment, where interacting with the full API might be cumbersome.

Prerequisites

1. Get credentials

To start using API, you’ll need to obtain a Bearer Token. Follow these steps to acquire your token:

a) Contact Us: Reach out to our support team or designated contact to request a Bearer Token. Provide relevant details about your use case and application.

b) Comming soon Self-service: Register in xeo.vision to generate token yourself.

Token security:

• Treat your Bearer Token as sensitive information.
• Keep it confidential and avoid sharing it publicly.

2. Familiarize yourself with Core Concepts

It's recommended to get familiar with Core Concepts before diving into API documentation.

Start with xeoService Rest API

1. Create a process:

curl --request POST \
  --url https://converter.xeo.vision/process \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "type": "ifc-xkt",
  "downloadUrl": "https://raw.githubusercontent.com/xeokit/xeokit-sdk/master/assets/models/ifc/Duplex.ifc"
}'

NOTE

Include token in the Authorization header of your API requests. The format should be:

Authorization: Bearer <your-token-here>

If successful, you will receive a response with the process ID.

{ 
  "id": "<process-id>"
}

2. Check the process status:

curl --request GET \
  --url https://converter.xeo.vision/process/<process-id> \
  --header 'Authorization: Bearer <token>'

The process may take some time to complete depending on the size of the model, but once it is completed, you will receive a response with the following data.

{
  "id": "5dcee47f-0ed7-4a26-ad4f-d93519ad05b8",
  "status": "process_completed",
  "type": "ifc-xkt",
  "viewerUrl": "https://sos-ch-gva-2.exo.io/...", 
  "updatedAt": "2024-07-10T09:30:02.712Z",
  "createdAt": "2024-07-10T09:30:00.784Z",
  "processOutputs": [
    {
      "id": "2ed9805d-443d-48b4-b2cb-77b5e8ecb637",
      "key": "8678cd12-5959-4172-8b43-db887c665ed5",
      "fileName": "glb-xkt.log",
      "fileType": "log",
      "fileSize": "1577",
      "updatedAt": "2024-07-10T09:30:02.703Z",
      "createdAt": "2024-07-10T09:30:02.703Z",
      "url": "https://sos-ch-gva-2.exo.io/..."
    },
    {
      "id": "53c8fac6-dc12-4d14-b60d-02c9ae014447",
      "key": "ec7aa964-dd6b-46c7-9bb0-f92a0c9ede05",
      "fileName": "ifc-glb.log",
      "fileType": "log",
      "fileSize": "535",
      "updatedAt": "2024-07-10T09:30:02.705Z",
      "createdAt": "2024-07-10T09:30:02.705Z",
      "url": "https://sos-ch-gva-2.exo.io/..."
    },
    {
      "id": "ee3bf3df-6117-4146-ad6e-be95eaf98cf7",
      "key": "88a66a4b-4c6d-47a7-a1ce-942627b39665",
      "fileName": "metadata.db",
      "fileType": "db",
      "fileSize": "200704",
      "updatedAt": "2024-07-10T09:30:02.706Z",
      "createdAt": "2024-07-10T09:30:02.706Z",
      "url": "https://sos-ch-gva-2.exo.io/..."
    },
    {
      "id": "59854b3e-5fd6-4bcb-8020-1a6c26b9b077",
      "key": "3dcf4efa-c39b-456b-b301-13d645972385",
      "fileName": "output.metadata.json",
      "fileType": "json",
      "fileSize": "104760",
      "updatedAt": "2024-07-10T09:30:02.708Z",
      "createdAt": "2024-07-10T09:30:02.708Z",
      "url": "https://sos-ch-gva-2.exo.io/..."
    },
    {
      "id": "d7efe3df-6ed1-4d10-ab7d-e6a1e395ff47",
      "key": "36c439d7-d6a4-442c-a940-cdad9086a645",
      "fileName": "output.xkt", 
      "fileType": "xkt", 
      "fileSize": "125805",
      "updatedAt": "2024-07-10T09:30:02.710Z",
      "createdAt": "2024-07-10T09:30:02.710Z",
      "url": "https://sos-ch-gva-2.exo.io/..."
    }
  ]
}

To download the xkt model, filter processOutputs by fileType: xkt and use the provided url.

NOTE

• The response contains links to other artifacts generated during the process, such as logs, metadata, etc.
• There is also a viewerUrl field that provides a convenient link to view the model on the xeo.vision portal.

3. Browse our API documentation to explore more endpoints and functionalities.

Start with xeoCli

Install CLI

1. Open Terminal (PowerShell preferred) and execute:

irm https://raw.githubusercontent.com/mmilian/xeo/refs/heads/main/install.ps1 | iex

Alternatively (step by step)

1. Download and review the script:

# Download the script
irm https://raw.githubusercontent.com/mmilian/xeo/refs/heads/main/install.ps1 -OutFile install.ps1
# Review the script
notepad install.ps1
# Execute the script
.\install.ps1

2. Restart the Terminal

To ensure that any environment variables changes takes effect.

3. [Optional] XEO_TOKEN environment variable

Set XEO_TOKEN ...

In PowerShell (Permanently for Current User):

[Environment]::SetEnvironmentVariable("XEO_TOKEN", "<your_token_here>", "User")

Alternatively (env for session, other shells)

In PowerShell (Current Session):

$env:XEO_TOKEN="<your_token_here>"

In Windows CMD (Permanently for Current User):

setx XEO_TOKEN="<your_token_here>""

After using setx, restart your terminal or log off and log back in to apply the changes.

In Windows CMD (Current Session):

set XEO_TOKEN="<your_token_here>"

WARNING

Do not have XEO_TOKEN? Go to docs.xeo.vision

4. Start using xeoCLI:

xeo convert https://raw.githubusercontent.com/xeokit/xeokit-sdk/master/assets/models/ifc/Duplex.ifc --type ifc-xkt --artifact

Explanation:

• xeo convert <url> initiates the conversion process with specifies IFC file (from the web).
• --type ifc-xkt sets the output format to xkt.
• --artifact drops artifacts to local folder.
• --log drops logs to local folder.