Aidbox
Search
K

Multibox box manager API

Multibox box life cycle RPC methods
Please start a discussion or contact us if you have question, feedback or suggestions.
Multibox box manager API uses Aidbox JSON RPC API.
Multibox API is accessible on the box manager URL. Please use an external REST client to access your Multibox server.

RPC methods available

multibox/fhir-versions

List FHIR versions supported by the server. One of these values must be used in multibox/create-box.
Example
Request
curl "multibox.example.host/rpc"
-H "Content-Type: application/json"
-d '{ "method": "multibox/fhir-versions" }'
Response
{
"result": [
"fhir-4.0.1",
"fhir-4.0.0",
"fhir-3.3.0",
"fhir-3.2.0",
"fhir-3.0.1",
"fhir-1.8.0",
"fhir-1.4.0",
"fhir-1.1.0",
"fhir-1.0.2"
]
}

multibox/create-box

Create a new box for the current user.
Parameters
Response
Parameter name
Required
Description
id
ID of the box to create
Must match /[a-z][a-z0-9]{4,}/
fhirVersion
FHIR version. Value must be from the multibox/versions response
description
description of the box to create
env
object with environment variables in
lower-kebab-case (notUPPER_SNAKE_CASE)
Property name
Value
Description
id
string
ID of the created box
description
string
Box description
fhirVersion
string
FHIR version
import
object
env
object
Envs used with BOX
participant
object
Contains requester information
Example
Request
curl "multibox.example.host/rpc"
-H "Content-Type: application/json"
-H "Authorization: Basic <credential-hash>"
-d '{
"method": "multibox/create-box",
"params": {
"id": "testid",
"fhirVersion": "fhir-4.0.1",
"description": "Test box",
"env": { "aidbox-stdout-pretty": "fatal" }
}
}'
Reponse
{
"result": {
"env": {
"aidbox-stdout-pretty": "fatal"
},
"import": {
"fhir-4.0.1": {}
},
"description": "Test box",
"fhirVersion": "fhir-4.0.1",
"participant": [
{
"role": "owner",
"user": {
"id": "admin",
"resourceType": "User"
}
}
],
"id": "testid",
"resourceType": "Box",
"meta": {
"lastUpdated": "2023-03-03T13:21:58.989147Z",
"createdAt": "2023-03-03T13:21:58.989147Z",
"versionId": "7"
}
}
}

Creating box with Aidbox configuration project

You can find more information about Aidbox configuration project here.
To create box with Aidbox configuration project you can use this environments:
Environment variable name
Description
box-project-git-url
Where to clone your project from. Aidbox substitutes it to git clone <url> command.
box-project-git-target--path
Where to clone your project to and where to read it from. Default value is a directory in /tmp
aidbox-zen-entrypoint
It is a namespaced symbol which is tagged with aidbox/system tag
Example with box-project-git-url
Request
curl "localhost:8888/rpc" \
-H "Content-Type: application/json" \
-H "Authorization: Basic <credential-hash>" \
-d '{
"method": "multibox/create-box",
"params": {
"id": "myboxname",
"fhirVersion": "fhir-4.0.1",
"env": {"box-project-git-url": "https://github.com/Aidbox/aidbox-project-template.git",
"aidbox-zen-entrypoint": "main/box"}
}
}'
Response
{
"result": {
"env": {
"box-project-git-url": "https://github.com/Aidbox/aidbox-project-template.git",
"aidbox-zen-entrypoint": "main/box"
},
"import": {
"fhir-4.0.1": {}
},
"fhirVersion": "fhir-4.0.1",
"participant": [
{
"role": "owner",
"user": {
"id": "admin",
"resourceType": "User"
}
}
],
"id": "myboxname",
"resourceType": "Box"
}
}
Example with box-project-git-target--path
Request
curl "localhost:8888/rpc" \
-H "Content-Type: application/json" \
-H "Authorization: Basic <credential-hash>" \
-d '{
"method": "multibox/create-box",
"params": {
"id": "myboxname",
"fhirVersion": "fhir-4.0.1",
"env": {"box-project-git-target--path": "/myproject",
"aidbox-zen-entrypoint": "main/box"}
}
}'
Response
{
"result": {
"env": {
"aidbox-zen-entrypoint": "main/box",
"box-project-git-target--path": "/myproject"
},
"import": {
"fhir-4.0.1": {}
},
"fhirVersion": "fhir-4.0.1",
"participant": [
{
"role": "owner",
"user": {
"id": "admin",
"resourceType": "User"
}
}
],
"id": "myboxname",
"resourceType": "Box"
}
}

multibox/list-boxes

List boxes available for the current user.
Parameters
Response
Expects no parameters
Property name
Type
Description
id
string
Box ID
fhirVersion
string
FHIR version of the box
constraints
object
Contains max and current number of boxes
Example
Request
curl "multibox.example.host/rpc"
-H "Content-Type: application/json"
-H "Authorization: Basic <credential-hash>"
-d '{
"method": "multibox/list-boxes"
}'
Resource
{
"result": {
"list": [
{
"id": "testid",
"fhirVersion": "fhir-4.0.1"
}
],
"constraints": null
}
}

multibox/get-box

Get box information.
Parameters
Response
Error
id (required): id of the box
Property name
Type
Description
description - box description meta - meta info about the box resource fhirVersion box-url access-url - link to get admin access participant- collection of user resources resourceType env - object with environment variables in lower-kebab-case (not in UPPER_SNAKE_CASE) access-token id
message- "You do not have access to this box" message - "No box with id - " message - "No user session"
Example
Response
{
"result": {
"description": "Test box",
"meta": {
"lastUpdated": "2023-03-03T13:21:58.989147Z",
"createdAt": "2023-03-03T13:21:58.989147Z",
"versionId": "7"
},
"fhirVersion": "fhir-4.0.1",
"box-url": "http://testid.127.0.0.1.nip.io:8788",
"access-url": "http://testid.127.0.0.1.nip.io:8788/__sudo?token=<token>&redirect-uri=/ui/console",
"participant": [
{
"role": "owner",
"user": {
"id": "admin",
"resourceType": "User"
}
}
],
"resourceType": "Box",
"env": {
"aidbox_stdout_pretty": "fatal"
},
"access-token": <token>,
"id": "testid",
"import": {
"fhir-4.0.1": {}
}
}
}

multibox/delete-box

This operation will drop the box database. Can not be undone!
Delete a box
Parameters
Response
Error
id (required): id of the box
description - box description meta - meta info about the box resource fhirVersion box-url access-url - link to get admin access participant- collection of user resources resourceType env - object with environment variables in lower-kebab-case (not in UPPER_SNAKE_CASE) access-token id
message - "Only owner can delete box." message - "Cannot delete box: \n <details>" message - FHIR OperationOutcome

multibox/drop-box-caches

Drop cache in every box
Parameters
Response
expects no parameters.
String: "ok".