API

Overview

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

Currently the API is read only, but we plan to extend it with modify and action capabilities. For the time being, we provide a Project List API, JSON exports and exports for Godot Engine.

In this chapter we will showcase how to create an API Token and use it in your app to get the exports.

In order to use the API you will have to be in an Arcweave Team plan. To see and upgrate your plan, you can go to your account plan page.

API Token

In order to use the API, you will have to create an API Token.

Go to your account page using your account icon on the top right corner. Account

If you are on a Team Plan, an option to Generate API Token will show up.

Generate Token

When you click this, a new API Token will be generated to use it to retrieve your project exports. The Generate API Token option will change to Show API Token.

Show Token

If you click the new option, a modal containing your API Token will show up, that you can copy.

Copy Token

{warning} This token gives access to all your project information! Be careful where you store and share it!

In case you want to generate a new API token and delete the old one, you can press the Generate New API Token button in the API Token modal.

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 three endpoints, a Project List, a JSON and a Godot Engine endpoint

Endpoint Method Headers
/api/user/projects GET Default
/api/{hash}/json GET Default
/api/{hash}/godot GET Default
/api/{hash}/unity 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.

{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.

Godot

The Godot endpoint will respond with a JSON containing the two Godot Files as strings. This Endpoint is used by our Godot Plugin to update the resources of the project.

{success} Success Response

Code 200

{
    "data": "[DATA EXPORT FILE CONTENTS]",
    "state": "[STATE EXPORT FILE CONTENTS]"
 }

{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 two files as strings. The first key, ArcscriptImplementations, contains the Arcsript Implementations of the nodes (elements, branch conditions, labels etc.) that include arcscript, transpiled in C#. The second key json, is an export similar to our JSON export. This Endpoint is used by our Unity Plugin to update the resources of the project.

{success} Success Response

Code 200

{
    "ArcscriptImplementations": "[ARCSRIPT IMPLEMENTATIONS FILE CONTENTS]",
    "json": "[JSON EXPORT FILE CONTENTS]"
 }

{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.