You can enable API access so that external applications can access your campaign data. Currently there are no public applications that can make use of this feature but the idea is that one day that will be the case (e.g. VTT integrations, discord bots, etc.) and this is the first step to that becoming a reality.
This option is only available for shared campaigns.
After enabling this experimental setting, the real option is available in the shared campaign settings to enable the API access.
After enabling this, you can set API keys for authentication. API keys can be generated for the owner access and/or for shared role access. The data available is the same as you would see when accessing the UI with that role.
Generating API Keys
API keys are key value pairs and are only shown when created. They are not stored so you need to take note of them when generating them. If you lose your key or secret then generate a new one by disabling the key and re-enabling it.
Owner Key
The owner key is used to access all your campaign data, as you see in the UI. It includes all objects and hidden notes. You can only have one owner API key and it will have a unique key and secret each time it is generated.
Click the owner API key header to generate a new key.
Shared Role Keys
Shared role keys have access to only the data that is shared with that role. You can have one key per role created and each will use the id of the role and create a new secret each time it is generated.
Click the plug icon in the access role list to generate a key for that role.
Using API Keys
API calls use basic authentication, which adds the Authorization: Basic XXXXXXXXXX header to all calls (where the value is the base64 encoded value of <apikey>:<secret>).
GET https://www.the-goblin.net/api/pub/{campaignid}Will return a json object with the entire campaign
GET https://www.the-goblin.net/api/pub/{campaignid}/{objectid}Will return a json object of the just the object requested
Campaign ID
The campaign ID is is visible in at the bottom-right of the main menu
Object ID
Object IDs are visible at the bottom of the object details panel when the object is selected
Example
curl -L 'https://www.the-goblin.net/api/pub/abcdefgh' -H 'Authorization: Basic YWJjZGVmZ2hpajoxMjM0NTY3ODkwMTIzNDU2Nzg5MDEy'Response
The data will be returned in json format, structured the same as the yaml export through the UI. There are no schema docs as the moment and it may occasionally change slightly.
{
"meta": {
"name": "API Test"
},
"connections": [
{
"id1": "ysafbptecy",
"id2": "sjopdwdwmn",
"note": "lives in",
"status": null,
"shared": true,
"order": 1
}
],
"notes": [],
"timeline": [
{
"id": "qmfbiapjyh",
"name": "Chapter 1",
"blurb": "# $[objectname]\n\n",
"order": 1,
"notes": [],
"start_date": "0001-01-01T00:00:00",
"end_date": "0001-01-01T00:00:00",
"shared": true
},
{
"id": "bsmqfsnfea",
"name": "Chapter 2",
"blurb": "# $[objectname]\n\n",
"order": 2,
"notes": [],
"start_date": "0001-01-01T00:00:00",
"end_date": "0001-01-01T00:00:00",
"shared": true
}
],
"blurb": "# $[objectname]\n\nEnter your campaign notes here!",
"locations": [
{
"locations": [
{
"locations": [],
"subtype": "location",
"id": "sjopdwdwmn",
"name": "Child Location",
"shared_name": null,
"status": 1,
"blurb": "# $[objectname]\n\n",
"order": 1,
"notes": [],
"chapters": [],
"consumables": [],
"shared": false,
"access_roles": [],
"primaryid": null,
"prominence": null,
"alias": null
}
],
"subtype": "location",
"id": "bldyenzrvd",
"name": "My First Location",
"shared_name": null,
"status": 1,
"blurb": "# $[objectname]\n\nNotes",
"order": 1,
"notes": [
{
"id": "qvrwqpeozq",
"blurb": "The first journal entry was logged here",
"created_at": "2024-06-30T19:48:14.7388012Z",
"campaign_note": true,
"shared": false
},
{
"id": "scqbgbwfwv",
"blurb": "Shortly followed by the second where @[](ysafbptecy) appeared",
"created_at": "2024-06-30T19:48:21.354773Z",
"campaign_note": true,
"shared": false
}
],
"chapters": [
"qmfbiapjyh"
],
"consumables": [],
"shared": true,
"access_roles": [],
"primaryid": null,
"prominence": null,
"alias": null
}
],
"creatures": [
{
"creatures": [],
"statblock": {
"shared": true,
"custom_statblock": "|HP|AC|Speed|\n|:---:|:---:|:---:|\n|number(name=hp,label=Hit Points,value=10) / number(name=maxhp,label=Max Hit Points,value=10)|number(label=Armor Class,name=ac,value=10)|number(name=speed,label=Speed,value=10) ft.|\n\n|str|dex|con|int|wis|cha|\n|:---:|:---:|:---:|:---:|:---:|:---:|\n|number(name=str,label=Strength,value=10)|number(name=dex,label=Dexterity,value=10)|number(name=con,label=Constitution,value=10)|number(name=int,label=Intelligence,value=10)|number(name=wis,label=Wisdom,value=10)|number(name=cha,label=Charisma,value=10)|\n|(mod5e(show_symbol,value=str))|(mod5e(show_symbol,value=dex))|(mod5e(show_symbol,value=con))|(mod5e(show_symbol,value=int))|(mod5e(show_symbol,value=wis))|(mod5e(show_symbol,value=cha))|",
"type": "custom"
},
"subtype": "npc",
"id": "ysafbptecy",
"name": "A Creature",
"shared_name": null,
"status": 0,
"blurb": "# $[objectname]\n\nNotes\n\n!!\n\nHidden Notes\n\n!!\n",
"order": 1,
"notes": [],
"chapters": [
"qmfbiapjyh",
"bsmqfsnfea"
],
"consumables": [],
"shared": true,
"access_roles": [],
"primaryid": null,
"prominence": null,
"alias": null
}
],
"organisations": [],
"quests": [],
"things": []
}