ReferenceDrive & Office API

Office editing

Opening Word, Excel and PowerPoint files in Bramble Office (needs the Docs, Sheets or Slides licence), creating new blank ones, and the start pages' recent files. The /wopi/... endpoints are how the editor reads and saves the file, each call carrying an access token Drive issued for that file; they're refused through the gateway.

Method	Path	Summary
GET	`/wopi/files/:id`	File details for the editor (WOPI CheckFileInfo)
GET	`/wopi/files/:id/contents`	File contents for the editor (WOPI GetFile)
POST	`/wopi/files/:id/contents`	Save from the editor (WOPI PutFile)
POST	`/wopi/files/:id`	Other editor requests (WOPI)
GET	`/api/v2/office/config`	Which Office apps you can use
GET	`/api/v2/office/recent`	The Docs / Sheets / Slides start pages: that kind's files the person can reach (their drive, their libraries, shared with them), newest first
POST	`/api/v2/office/:id/session`	Opens a file in the editor: the URL to post to and the token to post
POST	`/api/v2/office/new`	A new blank Word document, spreadsheet or presentation in a folder

#File details for the editor (WOPI CheckFileInfo)

GET/wopi/files/:id

Address: https://<your-org>.brambleit.cloud/drive/wopi/files/:id
Requires: None: public, or protected by a token in the address or body.

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`BaseFileName`	string
`BreadcrumbDocName`	string
`Size`	number
`Version`	array of any
`LastModifiedTime`	any
`OwnerId`	string
`UserId`	string
`UserFriendlyName`	string
`UserCanWrite`	any
`ReadOnly`	boolean
`UserCanNotWriteRelative`	boolean
`UserCanRename`	boolean
`SupportsRename`	boolean
`SupportsUpdate`	boolean
`SupportsLocks`	boolean
`PostMessageOrigin`	any
`ClosePostMessage`	boolean
`EnableInsertRemoteImage`	boolean
`EnableShare`	boolean
`IsAdminUser`	boolean
`IsAnonymousUser`	boolean

Example response

JSON

{
  "BaseFileName": "Example basefilename",
  "BreadcrumbDocName": "Example breadcrumbdocname",
  "Size": 12.5,
  "Version": [],
  "LastModifiedTime": null,
  "OwnerId": "string",
  "UserId": "string",
  "UserFriendlyName": "Example userfriendlyname",
  "UserCanWrite": null,
  "ReadOnly": false,
  "UserCanNotWriteRelative": false,
  "UserCanRename": false,
  "SupportsRename": false,
  "SupportsUpdate": false,
  "SupportsLocks": false,
  "PostMessageOrigin": null,
  "ClosePostMessage": false,
  "EnableInsertRemoteImage": false,
  "EnableShare": false,
  "IsAdminUser": false,
  "IsAnonymousUser": false
}

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/drive/wopi/files/42' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/wopi/files/42', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/drive/wopi/files/42",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/drive/wopi/files/42' -Headers $headers

#File contents for the editor (WOPI GetFile)

GET/wopi/files/:id/contents

Address: https://<your-org>.brambleit.cloud/drive/wopi/files/:id/contents
Requires: None: public, or protected by a token in the address or body.

Path parameters

Name	Type	Description
`id`required	integer

Response

A body, an empty body.

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents' -Headers $headers

#Save from the editor (WOPI PutFile)

POST/wopi/files/:id/contents

Address: https://<your-org>.brambleit.cloud/drive/wopi/files/:id/contents
Requires: None: public, or protected by a token in the address or body.
Headers: x-cool-wopi-timestamp, x-lool-wopi-timestamp

Path parameters

Name	Type	Description
`id`required	integer

Response 200

Field	Type	Description
`LastModifiedTime`	any

Example response

JSON

{
  "LastModifiedTime": null
}

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/drive/wopi/files/42/contents' -Headers $headers

#Other editor requests (WOPI)

POST/wopi/files/:id

Locks, "Save as", rename: not offered (see CheckFileInfo).

Address: https://<your-org>.brambleit.cloud/drive/wopi/files/:id
Requires: None: public, or protected by a token in the address or body.

Path parameters

Name	Type	Description
`id`required	integer

Response

An empty body.

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/drive/wopi/files/42' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/wopi/files/42', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/drive/wopi/files/42",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/drive/wopi/files/42' -Headers $headers

#Which Office apps you can use

GET/api/v2/office/config

Address: https://<your-org>.brambleit.cloud/drive/api/v2/office/config
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Drive.

Response 200

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/drive/api/v2/office/config' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/api/v2/office/config', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/drive/api/v2/office/config",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/drive/api/v2/office/config' -Headers $headers

#The Docs / Sheets / Slides start pages: that kind's files the person can reach (their drive, their libraries, shared with them), newest first

GET/api/v2/office/recent

Address: https://<your-org>.brambleit.cloud/drive/api/v2/office/recent
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Drive.

Query parameters

Name	Type	Description
`app`	any
`kind`	string
`q`	any

Response 200

Field	Type	Description
`items`	array of any
`locations`	array of any
`licensed`	boolean

Example response

JSON

{
  "items": [],
  "locations": [],
  "licensed": false
}

Errors

Status	Message
400	Unknown kind

Example request

Bash

curl -X GET 'https://<your-org>.brambleit.cloud/drive/api/v2/office/recent' \
  -H "X-API-Key: $BRAMBLE_KEY"

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/api/v2/office/recent', {
  method: 'GET',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY },
});
const data = await res.json();

Python

import os, requests

r = requests.get(
    "https://<your-org>.brambleit.cloud/drive/api/v2/office/recent",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
Invoke-RestMethod -Method GET -Uri 'https://<your-org>.brambleit.cloud/drive/api/v2/office/recent' -Headers $headers

#Opens a file in the editor: the URL to post to and the token to post

POST/api/v2/office/:id/session

Opens a file in the editor: the URL to post to and the token to post. Editors and owners edit; viewers (or ?mode=view) get it read-only.

Address: https://<your-org>.brambleit.cloud/drive/api/v2/office/:id/session
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Drive.

Path parameters

Name	Type	Description
`id`required	number

Request body JSON

Name	Type	Description
`mode`	any

Response 200

Field	Type	Description
`url`	string
`access_token`	string
`access_token_ttl`	any
`write`	any
`item`	any
`path`	string

Example response

JSON

{
  "url": "https://example.com/…",
  "access_token": "…",
  "access_token_ttl": null,
  "write": null,
  "item": null,
  "path": "string"
}

Errors

Status	Message
503	Office editing is not switched on
400	Only files can be opened
409	This file is still being moved to new storage — try again later

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/drive/api/v2/office/12.5/session' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"…"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/api/v2/office/12.5/session', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"mode":"…"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/drive/api/v2/office/12.5/session",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"mode":"…"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"mode":"…"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/drive/api/v2/office/12.5/session' -Headers $headers -ContentType 'application/json' -Body $body

#A new blank Word document, spreadsheet or presentation in a folder

POST/api/v2/office/new

Address: https://<your-org>.brambleit.cloud/drive/api/v2/office/new
Requires: Signed-in session, X-API-Key, or a Bramble app access token (Authorization: Bearer).
Licence: Drive.

Request body JSON

Name	Type	Description
`kind`	string
`name`	string

Response 201

Errors

Status	Message
503	Office editing is not switched on
400	Choose a document, spreadsheet or presentation

Example request

Bash

curl -X POST 'https://<your-org>.brambleit.cloud/drive/api/v2/office/new' \
  -H "X-API-Key: $BRAMBLE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"kind":"string","name":"Example name"}'

JavaScript

const res = await fetch('https://<your-org>.brambleit.cloud/drive/api/v2/office/new', {
  method: 'POST',
  headers: { 'X-API-Key': process.env.BRAMBLE_KEY, 'Content-Type': 'application/json' },
  body: JSON.stringify({"kind":"string","name":"Example name"}),
});
const data = await res.json();

Python

import os, requests

r = requests.post(
    "https://<your-org>.brambleit.cloud/drive/api/v2/office/new",
    headers={"X-API-Key": os.environ["BRAMBLE_KEY"]},
    json={"kind":"string","name":"Example name"},
)
r.raise_for_status()
data = r.json()

PowerShell

$headers = @{ 'X-API-Key' = $env:BRAMBLE_KEY }
$body = '{"kind":"string","name":"Example name"}'
Invoke-RestMethod -Method POST -Uri 'https://<your-org>.brambleit.cloud/drive/api/v2/office/new' -Headers $headers -ContentType 'application/json' -Body $body

Was this page helpful?