Scabard API Documentation

Scabard API Documentation

Authentication

Scabard needs to authenticate that your users have granted your app access to their campaigns.

Your app will need to pass the username of your user, along with their API access key as headers for each request.

To test from the command line, use curl with the -H option:

curl -X GET https://www.scabard.com/api/v0/campaign/121/event -H "username: stolph" -H "accessKey: 8301789723432159092"

To grant your app access, your user will need to:
  • Go to their user profile page on Scabard (https://www.scabard.com/pbs/[username]) while logged in.
  • Click the down arrow button and select "API Access Key"
  • Enter their username and copy/paste this key into a dialog you present to the user.

The user's access key expires 24 hr after it is generated. Prompt your user to get another one if it expires.

HTTP Status Codes

Apps that use the API

Foundry Module: Scabard Connect
by professorx00

  • 200 - Success.
  • 401 - Invalid username or accessKey. Possibly one that is expired.
  • 403 - Valid username and accessKey but the user does not have access to the resource. Such as a campaign they are not the GM of.
  • 404 - Invalid uri.
  • 429 - Too many requests. Slow down how fast you call the API.
  • 500+ - Unexpected server error. Please reach out to me (with details, but be sure to exclude your accessKey for security): #api_dev_support (Discord) or [email protected]

List of User's Campaigns

Request:

GET https://www.scabard.com/api/v0/campaign

Response:

Returns list of all GM's campaigns (under 'rows')

Campaign

Request:

GET https://www.scabard.com/api/v0/campaign/[campaign_id]
  • campaign_id is a number

Response:

Returns details one of the GM's campaigns (under 'main'). Plus a summary of every page in the campaign (under 'rows').

Pages of a certain concept

Request:

GET https://www.scabard.com/api/v0/campaign/[campaign_id]/[concept]
  • campaign_id is a number
  • concept is lower case and can be in [character, group, event, etc].

Response:

Returns a summary of every page of a certain concept in the campaign (under 'rows').

A specific page in a campaign

Request:

GET https://www.scabard.com/api/v0/campaign/[campaign_id]/[concept]/[thing_id]
  • campaign_id is a number
  • concept is lower case and can be in [character, group, event, etc].
  • thing_id is a number

Response:

Returns details of a specific page in the GM's campaign (under 'main').

Coming soon: Plus a summary of pages it's connected to (under 'conns').

Saving to a page in a campaign

Request:

curl -X POST https://www.scabard.com/api/v0/campaign/[campaign_id]/[concept]/[thing_id] -H "username: stolph" -H "accessKey: 8301789723432159092" -d 'name=The Milky Way' -d 'briefSummary=From POST Scabard API 3b' -d 'concept=Vehicle'
  • campaign_id is a number
  • concept is lower case and can be in [character, group, event, etc].
  • thing_id is a number

Response:

Returns isSuccess: true or false

Sending JSON

curl -X POST https://www.scabard.com/api/v0/campaign/[campaign_id]/[concept]/[thing_id] -H "username: stolph" -H "accessKey: 8301789723432159092" -H "content-type: application/json" -d '{"briefSummary":"Dwarven god of greed","isSecret":"false","description":"blah blah","secrets": " ", "gmSecrets": "Just secrets", "name": "Abbathor","concept": "Character"}'