Team Workspace API

Teams with Team+ workspaces can retrieve and update their workspace diagrams using an API. Contact us to upgrade to a Team+ workspace for API access and other benefits.

Setup
Using the API

Workspace admins will need to configure their workspace to enable API access. API access is controlled by a combination of access keys and allow-listed IP addresses. Systems using the API will need a valid access key and orginiate from an allowed IP address.

API users will need a valid access key with appropriate permissions. Follow these steps to create an access key:

1. From you team workspace homepage, click “API Access” in the top-right of the app:

2. From the API Access page, click “Add access key”

3. In the dialog that appears, give your new key a name and an expriation time:

4. Click “Add permission” to give the key one or more permissions:

Permissions can grant read access, write access, or both. The permission value must be a diagram name (case-senstive). Permissions can also be granted for all diagrams in an entire folder (and its sub-folders) by using an asterisk (*). For instance, the value Common/* grants permissions for all diagrams under the Common folder and its sub-folders.

Note: To grant access to all diagrams in the workspace, use a single asterisk (*) for the permission value. However, it is strongly recommended to use fine-grained permissions instead.

5. When done adding permissions, click “Create access key”. Your key will appear in the next dialog. Be sure to record your key, as it is only shown once and cannot be recovered.

API requests must originate from an IP address on the allow-list. All other requests will be denied. Follow these steps to add an IP address to the allow-list:

1. From you team workspace homepage, click “API Access” in the top-right of the app:

2. From the API Access page, click “Add IP address”:

3. In the dialog that appears, add the IP address and, optionally, a note. The IP address can be in either IPv4 or IPv6 format:

4. When ready, click the “Add IP address” button.

API calls are made to the address https://api.ilograph.com/m0/ followed by your team workspace domain and the path to the diagram, like so:

https://api.ilograph.com/m0/@TeamName/path/to/diagram

The green portion is the base API address.

The red portion is your team name. Be sure to include the @ sign.

The blue portion is the path to the diagram you wish to retrieve or modify. For diagrams in the workspace root (i.e. not in a folder), this will be just the diagram name.

All request must include a valid access key (see above) in the header accessKey. Requests without this header will be denied.

API request support three HTTP methods:

GET retrieves the diagram (requires read permissions).

PUT updates the diagram. Include the yaml as plain text in the request body (requires write permissions).

Note: Only existing diagrams may be updated. Diagrams cannot be created or deleted via API.

HEAD returns an empty body, but includes the Last-Modified header, so you can check if the diagram is out of date. Works with either read or write permissions.

For questions, please contact support at support@ilograph.com.