API

Overview

Arcweave offers an API that Team workspaces can use to generate exports for their projects.

Currently, the API is read-only and provides:

  • a Project List API
  • JSON exports
  • game engine exports (Unreal, Unity, and Godot).

{success} The API is available to Team workspaces only.

API tokens

In order to use the API, you must have one or more API tokens.

To create a new API token:

  • Go to your workspace's API section
  • Press + Create new key.

To edit or delete an API token:

  • Go to your workspace's API section
  • click on the ••• symbol at the end of the key's row and choose Rename or Remove.

{info} For a member to access the API section of a Team workspace, they must have permissions to View API keys, Create API keys, and Manage API.


{warning} An API token gives access to your workspace's project information! Be careful where you store and share it! Do not expose your key in the browser or other client-side code.

Usage

Default Headers

The default headers to use the endpoint are the authorization header containing the API Token as a Bearer token and the Accept header with an application/json value 

Authorization: Bearer [API Token]
 Accept: application/json

So to make a request using PHP for the JSON export of the project 4OlzRvblqP this would be:

$response = $client->request('GET', '/api/4OlzRvblqP/json', [
    'headers' => [
        'Authorization' => 'Bearer '.$token,
        'Accept' => 'application/json',
    ],
 ]);

Endpoints

So far, we provide five endpoints for the following: the Project list and our JSON, Unreal, Unity and Godot exports.

Endpoint Method Headers
/api/user/projects GET Default
/api/{hash}/json GET Default
/api/{hash}/unreal GET Default
/api/{hash}/unity GET Default
/api/{hash}/godot GET Default

The hash option in the endpoints, is the Project hash that we want to retrieve the information for. You can find it by looking at the URL of your project. The default URL format is: 

arcweave.com/app/project/[hash]?board=[board-id]&scale=1&coords=[x],[v]

So i.e. for the Project URL 

https://arcweave.com/app/project/4OlzRvblqP?board=630fdb8a-48d6-473e-9974-2460f7eb2b41&scale=0.466508&coords=-9919.42,-9879.4

The Project Hash is 4OlzRvblqP, so our endpoints would be /api/4OlzRvblqP/json, /api/4OlzRvblqP/godot etc.

Project List

The Project List will respond with an array of your projects.

{success} Success Response

Code 200

[
  {
    "hash": "ra6XRNxl3G",
    "name": "The Castle",
    "updatedAt": "2023-03-09T18:47:35.000000Z",
    "createdAt": "2023-03-09T13:43:32.000000Z",
    "role": "owner"
  },
  {
    "hash": "VO641d70xY",
    "name": "Untitled project",
    "updatedAt": "2023-03-09T12:57:20.000000Z",
    "createdAt": "2022-11-18T17:37:04.000000Z",
    "role": "editor"
  },
  {
    "hash": "qMEvPRQ08Z",
    "name": "Regrets",
    "updatedAt": "2022-10-03T15:11:58.000000Z",
    "createdAt": "2022-10-03T15:08:36.000000Z",
    "role": "owner"
  },
  {
    "hash": "jlMasdlq5e",
    "name": "Restored - The Castle",
    "updatedAt": "2022-9-13T17:24:25.000000Z",
    "createdAt": "2022-8-03T10:28:39.000000Z",
    "role": "viewer"
  }
]

Each project object has 5 fields:

Property Type Value
hash String The hash ID of the Project
name String The name of the Project
updatedAt String The time of the last update (UTC)
createdAt String The create datetime fo the project (UTC)
role String The user's role in the project. Can be ['owner', 'editor', 'viewer']

The Project List is in Descending Order based on the updatedAt field.

{danger} Error Response

Code 500

There was an error retrieving the user's projects.

Code 403

You have insufficient permissions to make this request. Please make sure you are still on a Team Account.

JSON

The JSON endpoint will respond with the JSON of the project, similar to a JSON Export.

For this endpoint in the query string you may define an array of board and folder ids if you need to limit the response to specific boards only.

  /api/{hash}/json?boardIds[]={boardId1}&boardIds[]={boardId2}&...

{success} Success Response

Code 200

{
  "startingElement": "38375689-9e4d-430e-954c-65205eb622fe",
  "boards": {
    "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": {
      "name": "Root",
      "root": true,
      "children": [
        "630fdb8a-48d6-473e-9974-2460f7eb2b41",
        "733b1cc4-6d51-4ad6-9fba-444b4f2d98f3"
      ]
    },
    "630fdb8a-48d6-473e-9974-2460f7eb2b41": {
      "name": "Main Board",
      "notes": [
        "eda3ed5a-bdd5-4981-a72f-c7847630310a",
        "585c89a5-a16c-44db-9346-6e2725afcd88",
        "5f45b936-1a0f-4834-87c3-579fb72329b1",
        "0d580890-add4-4750-9b0c-64a9be4bd9be",
        "045fcf7a-0e29-4f29-a6b3-f1be825832ed",
        "27bcf38e-cef9-4413-b4c9-97e6c7300ec3",
        "c917680a-9884-41fb-832c-7ac41f87c520"
      ],
    [...]
 }

{danger} Error Response

Code 500

There was an error during the export of the project.

Code 403

You have insufficient permissions for exporting this project. Please make sure you are still on a Team Account, you are using the correct Hash ID and you are an Owner/Editor of the project.

Unreal

The Unreal endpoint will respond with a JSON containing the project settings in a key called project. The project settings are similar to the value of the JSON export. This Endpoint is used by our Unreal Plugin to update the resources of the project.

{success} Success Response

Code 200

{
  "project": {
    "startingElement": "38375689-9e4d-430e-954c-65205eb622fe",
    "boards": {
      "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": {
        "name": "Root",
        "root": true,
        "children": [
          "630fdb8a-48d6-473e-9974-2460f7eb2b41",
          "733b1cc4-6d51-4ad6-9fba-444b4f2d98f3"
        ]
      },
      "630fdb8a-48d6-473e-9974-2460f7eb2b41": {
        "name": "Main Board",
        "notes": [
          "eda3ed5a-bdd5-4981-a72f-c7847630310a",
          "585c89a5-a16c-44db-9346-6e2725afcd88",
          "5f45b936-1a0f-4834-87c3-579fb72329b1",
          "0d580890-add4-4750-9b0c-64a9be4bd9be",
          "045fcf7a-0e29-4f29-a6b3-f1be825832ed",
          "27bcf38e-cef9-4413-b4c9-97e6c7300ec3",
          "c917680a-9884-41fb-832c-7ac41f87c520"
        ],
      [...]
 }

{danger} Error Response

Code 500

There was an error during the export of the project.

Code 403

You have insufficient permissions for exporting this project. Please make sure you are still on a Team Account, you are using the correct Hash ID and you are an Owner/Editor of the project.

Unity

The Unity endpoint will respond with a JSON containing the project settings in a key called project. The project settings are similar to the value of the JSON export. This Endpoint is used by our Unity Plugin to update the resources of the project.

{success} Success Response

Code 200

{
  "project": {
    "startingElement": "38375689-9e4d-430e-954c-65205eb622fe",
    "boards": {
      "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": {
        "name": "Root",
        "root": true,
        "children": [
          "630fdb8a-48d6-473e-9974-2460f7eb2b41",
          "733b1cc4-6d51-4ad6-9fba-444b4f2d98f3"
        ]
      },
      "630fdb8a-48d6-473e-9974-2460f7eb2b41": {
        "name": "Main Board",
        "notes": [
          "eda3ed5a-bdd5-4981-a72f-c7847630310a",
          "585c89a5-a16c-44db-9346-6e2725afcd88",
          "5f45b936-1a0f-4834-87c3-579fb72329b1",
          "0d580890-add4-4750-9b0c-64a9be4bd9be",
          "045fcf7a-0e29-4f29-a6b3-f1be825832ed",
          "27bcf38e-cef9-4413-b4c9-97e6c7300ec3",
          "c917680a-9884-41fb-832c-7ac41f87c520"
        ],
      [...]
 }

{danger} Error Response

Code 500

There was an error during the export of the project.

Code 403

You have insufficient permissions for exporting this project. Please make sure you are still on a Team Account, you are using the correct Hash ID and you are an Owner/Editor of the project.

Godot

The Godot endpoint will respond with a JSON containing the project settings in a key called project. The project settings are similar to the value of the JSON export. This Endpoint is used by our Godot Plugin to update the resources of the project.

{success} Success Response

Code 200

{
  "project": {
    "startingElement": "38375689-9e4d-430e-954c-65205eb622fe",
    "boards": {
      "2ad15ff6-f2ba-4f1d-9d9d-68938c683d7e": {
        "name": "Root",
        "root": true,
        "children": [
          "630fdb8a-48d6-473e-9974-2460f7eb2b41",
          "733b1cc4-6d51-4ad6-9fba-444b4f2d98f3"
        ]
      },
      "630fdb8a-48d6-473e-9974-2460f7eb2b41": {
        "name": "Main Board",
        "notes": [
          "eda3ed5a-bdd5-4981-a72f-c7847630310a",
          "585c89a5-a16c-44db-9346-6e2725afcd88",
          "5f45b936-1a0f-4834-87c3-579fb72329b1",
          "0d580890-add4-4750-9b0c-64a9be4bd9be",
          "045fcf7a-0e29-4f29-a6b3-f1be825832ed",
          "27bcf38e-cef9-4413-b4c9-97e6c7300ec3",
          "c917680a-9884-41fb-832c-7ac41f87c520"
        ],
      [...]
 }

{danger} Error Response

Code 500

There was an error during the export of the project.

Code 403

You have insufficient permissions for exporting this project. Please make sure you are still on a Team Account, you are using the correct Hash ID and you are an Owner/Editor of the project.