REST API Documentation

The REST API requires at least xltrail v4.0.2

API Key

In xltrail, go to Settings > Access > API Key to create and copy your API key.

NOTE: There are two types of API keys, Personal API Key and Group API Key. As of now, the Group API Key can only be used for incoming webhooks. For anything API related, use the Personal API Key.

Headers

All requests must include the following headers:

X-API-KEY: your_api_key
Accept: application/json
Content-Type: application/json

Base URL

The base URL is the URL of your xltrail app + /api. If you are using the cloud, it is https://app.xltrail.com/api. Always prepend the base URL in front of the endpoints below.

Endpoints

GET /repos

Lists all repositories.

Sample Request

curl --request GET \
  --header "X-API-KEY: your_api_key" \
  --header "Accept: application/json" \
  --header "Content-type: application/json" \
  "https://app.xltrail.com/api/repos"

Sample Response

[
  {
    "id": "62ab6fb3-a152-44bd-b566-59acce5eff24",
    "name": "Accounting",
    "full_name": "Accounting",
    "url": null,
    "created_at": "2024-03-14T13:52:56.866088+00:00"
  },
  {
    "id": "0500a155-d85a-4eae-a45e-5ec4087b4b43",
    "name": "salesplan",
    "full_name": "github.com/fzumstein/salesplan.git",
    "url": "https://github.com/fzumstein/salesplan.git",
    "created_at": "2024-03-14T13:52:16.272240+00:00"
  }
]

POST /repos

Create a new repository.

Sample Request (Drag and drop)

curl --request POST \
  --header "X-API-KEY: your_api_key" \
  --header "Accept: application/json" \
  --header "Content-type: application/json" \
  --data '{"name": "Accounting"}' \
  "https://app.xltrail.com/api/repos"

Sample Response (Drag and drop)

{
  "id": "62ab6fb3-a152-44bd-b566-59acce5eff24",
  "name": "Accounting",
  "full_name": "Accounting",
  "url": null,
  "created_at": "2024-03-14T13:52:56.866088+00:00"
}

Sample Request (external Git repo)

curl --request POST \
  --header "X-API-KEY: your_api_key" \
  --header "Accept: application/json" \
  --header "Content-type: application/json" \
  --data '{"url": "https://github.com/fzumstein/salesplan.git", "username": "...", "password": "..."}' \
  "https://app.xltrail.com/api/repos"

Sample Response (external Git repo)

{
  "id": "0500a155-d85a-4eae-a45e-5ec4087b4b43",
  "name": "salesplan",
  "full_name": "github.com/fzumstein/salesplan.git",
  "url": "https://github.com/fzumstein/salesplan.git",
  "created_at": "2024-03-14T13:52:16.272240+00:00"
}

GET /repos/{repo}/contents

Get a workbook or the content of a folder.

Sample Request (entire project)

Returns the content of the my-repo repository and writes it to repo.zip.

curl \
  --output repo.zip \
  --header "X-API-KEY: your_api_key" \
  --request GET \
  "https://app.xltrail.com/api/repos/my-repo/contents"

Sample Request (folder)

Returns the /path/to/folder folder content of the my-repo repository and writes it to folder.zip.

curl \
  --output repo.zip \
  --header "X-API-KEY: your_api_key" \
  --request GET \
  "https://app.xltrail.com/api/repos/my-repo/contents/path/to/folder"

Sample Request (folder on branch dev)

Returns the /path/to/folder folder content of the dev branch of the my-repo repository and writes it to folder.zip.

curl \
  --output repo.zip \
  --header "X-API-KEY: your_api_key" \
  --request GET \
  "https://app.xltrail.com/api/repos/my-repo/contents/path/to/folder?branch=dev"

Sample Request (workbook)

Returns the /path/to/folder/workbook1.xlsx workbook and writes it to workbook1.xlsx.

curl \
  --output repo.zip \
  --header "X-API-KEY: your_api_key" \
  --request GET \
  "https://app.xltrail.com/api/repos/my-repo/contents/path/to/folder/workbook1.xlsx"

REST API