API: Characters

The Characters API methods allow for retrieving information about characters

Attributes

Public (always available)

  • id - identifier - A unique identifier for the character. This will never change. (read only)
  • slug - string - A URL-friendly slug for the campaign. The user can change this. Some characters do not have slugs.
  • name - string - The character's name.
  • character_url - string - The URL to the character's page. (read only)
  • avatar_url - string - The URL to the character's avatar image. Only present if the character has a custom image. (read only)
  • campaign - campaign mini-object The campaign that this character belongs to. (Some older characters are still 'orphans' and do not have a campaign) (read only)
  • visibility - string - The visibility of the character, inherited from the campaign. Can be 'public', 'friends', or 'private' (All orhpaned characters are public)
  • created_at - timestamp - Indicates when the character was first created. ISO-8601 timestamp (read only)
  • updated_at - timestamp - Indicates when the character was last updated. ISO-8601 timestamp (read only)

Public / Private / Friends Visibility (availability depends on campaign's visibility)

  • author -user mini-object - The author. In the case of a PC, this is the player.
  • is_player_character - boolean - true if this character is a player character, false otherwise
  • is_game_master_only - boolean - true if this character is visibile only to the GM, false otherwise
  • dynamic_sheet_template - dynamic sheet template mini-object - The dynamic sheet template (if any) used by this character.
  • dynamic_sheet - JSON object - The dynamic sheet data (if any) for this character. Make sure to read the notes about the dynamic sheet data below.
  • description - string - The raw text of the character's description field.
  • description_html - string - The parsed and rendered HTML for the description field. (read only)
  • bio - string - The raw text of the character's bio field.
  • bio_html - string - The parsed and rendered HTML for the bio field. (read only)
  • tags - array - A list of tags applied to this character.

GM only (available only to the GM and any co-GMs)

  • game_master_info - string - The raw text of the GM Only info field.
  • game_master_info_markup - string - The parsed and rendered HTML for the GM Only info field. (read only)

Notes

Dynamic Sheets

The dynamic sheet data is stored as a JSON object, essentially a key-value (ie. hash) object. If you wish to modify the dynamic sheet, you must submit the entire dynamic sheet object. In other words, the dynamic sheet is not updated or modified, but replaced. Be very careful when modifying dynamic sheet data, as you can wipe out someone's entire dynamic sheet by passing an empty object for the dynamic sheet.

If you don't know what you're doing with the dynamic sheet data, ASK SOMEONE!!!

Methods

Index (List)

URL: http://api.obsidianportal.com/v1/campaigns/ campaign_id/characters.format
HTTP Verb: GET
Requires Authentication: Yes
Required Parameters:

  • campaign_id - identifier - The ID of the campaign to retrieve a character list from.

Optional Parameters: None
Response: A list of characters for a campaign.

Notes

1) Missing fields
To conserve bandwidth, the dynamic_sheet, bio, bio_html, description, description_html, game_master_info, and game_master_info_html fields are not returned. If you need the full text of these fields you will need to retrieve the pages individually.

2) Character visibility
The list of characters returned depends on the visibility of the campaign and the identity of the logged in user. It breaks down as follows:

  • public campaign, non-GM - All non gm-only characters
  • public campaign, GM - All characters
  • private campaign, non-player, non-GM - HTTP 403
  • private campaign, player - All non gm-only characters
  • private campaign, GM - All characters

Example

Request 

http://api.obsidianportal.com/v1/campaigns/5b6ef1e0f24411dfba8140403656340d/characters.json

Response 

[
  {
   'id' : 'c06993fcf24411dfba8140403656340d',
   'slug' : 'smoth',
   'name' : 'Smoth Harkshire',
   'character_url' : 'http://www.obsidianportal.com/campaigns/kensing/characters/smoth',
   'campaign' : {
    'id' : '5b6ef1e0f24411dfba8140403656340d',
    'name' : 'Kensing',
    'slug' : 'kensing',
    'campaign_url' : 'http://www.obsidianportal.com/campaigns/kensing'
   },
   'visibility' : 'public',
   'author' : {
    'id' : '1b938f60f24211dfba7940403656340d',
    'username' : 'Micah',
    'profile_url' : 'http://www.obsidianportal.com/profile/Micah'
   },
   'is_player_character' : true,
   'tags' : ['pc', 'rogue', 'transmuter'],
   'created_at' : '2007-04-24T21:42:13Z',
   'updated_at' : '2010-01-18T04:50:09Z',
   'is_game_master_only' : false
  },
  {
   'id' : 'c069f75cf24411dfba8140403656340d',
   'name' : 'Cleric Elogrin',
   'character_url' : 'http://www.obsidianportal.com/campaigns/kensing/characters/35',
   'campaign' : {
    'id' : '5b6ef1e0f24411dfba8140403656340d',
    'name' : 'Kensing',
    'slug' : 'kensing',
    'campaign_url' : 'http://www.obsidianportal.com/campaigns/kensing'
   },
   'visibility' : 'public',
   'author' : {
    'id' : '1b938f60f24211dfba7940403656340d',
    'username' : 'Micah',
    'profile_url' : 'http://www.obsidianportal.com/profile/Micah'
   },
   'is_player_character' : false,
   'tags' : ['istivin', 'cleric', 'heironius'],
   'created_at' : '2007-04-24T22:44:28Z',
   'updated_at' : '2010-01-18T05:37:37Z',
   'is_game_master_only' : false
  }
 ]

Show

URL: http://api.obsidianportal.com/v1/campaigns/ campaign_id/characters/id.format
HTTP Verb: GET
Requires Authentication: Yes
Required Parameters:

  • campaign_id - identifier - The ID of the campaign to retrieve the character from.
  • id - identifier - The ID of the character to retrieve. You can also use the character slug (see use_slug below)

Optional Parameters:

  • use_slug - boolean - When set to 'true', or '1', the character will be looked up by slug instead of id. Note: The campaign_id must be an identifier, not a slug.

Response Code: 200
Response Body: A single character for a campaign.

Example

Request 

http://api.obsidianportal.com/v1/campaigns/5b6ef1e0f24411dfba8140403656340d/characters/c05826a8f24411dfba8140403656340d.json

Response 

{
 'id' : 'c05826a8f24411dfba8140403656340d',
 'slug' : 'ashaurok',
 'name' : 'Ashaurok',
 'character_url' : 'http://www.obsidianportal.com/campaigns/kensing/characters/ashaurok',
 'campaign_id' : '5b6ef1e0f24411dfba8140403656340d',
 'tagline' : 'Ice Wzardress of Nent',
 'is_player_character' : false,
 'author' : {
    'id' : '1b938f60f24211dfba7940403656340d',
    'username' : 'Micah',
    'profile_url' : 'http://www.obsidianportal.com/profile/Micah'
   },
 'dynamic_sheet_template' : {
  'id' : '4a938f60f24211dfba7940403656340d',
  'name' : 'Chainsaws DnD 3.5',
  'slug' : 'chainsaw_dnd_35'
 },
 'dynamic_sheet' : {
  'race' : 'Human',
  'class' : 'Wizard',
  'level' : '20'
 },
 'description' : 'Level 20 wizard',
 'description_html' : ' 
Level 20 wizard
',
 'bio' : 'Mentor of Smoth',
 'bio_html' : '
Mentor of Smoth
',
 'tags' : ['nent', 'wizard'],
 'created_at' : '2007-04-24T21:42:13Z',
 'updated_at' : '2010-01-18T04:50:09Z',
 'is_game_master_only' : false,
 'game_master_info' : 'Secret info here',
 'game_master_info_html' : '
Secret info here
',
}

Create

URL: http://api.obsidianportal.com/v1/campaigns/ campaign_id/characters.format
HTTP Verb: POST
Requires Authentication: Yes
Required Parameters:

  • campaign_id - identifier - The ID of the campaign to create a character in.

Optional Parameters: None
Response Code: 201
Response Body: A single character.

Example

Request

Request Body 

{
 'character' : {
  'name' : 'BBEG',
  'tagline' : 'Awaiting in his fortress',
  'description' : 'Level 30 wizard',
  'bio' : 'Dark lord of destruction, watching from on high',
  'game_master_info' : 'Actually quite cuddly',
  'is_game_master_only' : true,
  'dynamic_sheet_template_id' : '4a938f60f24211dfba7940403656340d',
  'dynamic_sheet' : {
   'race' : 'Drow',
   'class' : 'Wizard',
   'level' : '30'
  }
 }
}

Response 

{
 'id' : 'e06993fcf24411dfba8140403656340d',
 'slug' : 'bbeg',
 'name' : 'BBEG',
 'tagline' : 'Awaiting in his fortress',
 'wiki_page_url' : 'http://www.obsidianportal.com/campaigns/kensing/characters/bbeg',
 'campaign' : {
    'id' : '5b6ef1e0f24411dfba8140403656340d',
    'name' : 'Kensing',
    'slug' : 'kensing',
    'campaign_url' : 'http://www.obsidianportal.com/campaigns/kensing'
   },
 'dynamic_sheet_template' : {
  'id' : '4a938f60f24211dfba7940403656340d',
  'name' : 'Chainsaws DnD 3.5',
  'slug' : 'chainsaw_dnd_35'
 },
 'dynamic_sheet' : {
  'race' : 'Drow',
  'class' : 'Wizard',
  'level' : '30'
 },
 'description' : 'Level 30 wizard',
 'description_html' : '
Level 30 wizard
',
 'bio' : 'Dark lord of destruction, watching from on high',
 'bio_html' : '
Dark lord of destruction, watching from on high
',
 'is_player_character' : false,
 'author' : {
    'id' : '1b938f60f24211dfba7940403656340d',
    'username' : 'Micah',
    'profile_url' : 'http://www.obsidianportal.com/profile/Micah'
   },
 'created_at' : '2010-11-01T21:42:13Z',
 'updated_at' : '2010-11-01T21:42:13Z',
 'is_game_master_only' : true,
 'game_master_info' : 'Actually quite cuddly',
 'game_master_info_html' : '
Actually quite cuddly
'
}

Update

URL: http://api.obsidianportal.com/v1/campaigns/ campaign_id/characters/id.format
HTTP Verb: PUT
Requires Authentication: Yes
Required Parameters:

  • campaign_id - identifier - The ID of the campaign to retrieve a character from.
  • id - identifier - The ID of the character to update.

Optional Parameters: None
Response Code: 200
Response Body: A single character.

Example

Request 

http://api.obsidianportal.com/v1/campaigns/5b6ef1e0f24411dfba8140403656340d/characters/e06993fcf24411dfba8140403656340d.json

Request Body 

{
 'character' : {
  'bio' : 'Has joined the party as a mentor',
  'game_master_info' : 'Still is the bbeg',
  'is_game_master_only' : false,
  'dynamic_sheet' : {
   'race' : 'Half-Drow'
  }
 }
}

Response 

{
 'id' : 'e06993fcf24411dfba8140403656340d',
 'slug' : 'bbeg',
 'name' : 'BBEG',
 'tagline' : 'Awaiting in his fortress',
 'wiki_page_url' : 'http://www.obsidianportal.com/campaigns/kensing/characters/bbeg',
 'campaign' : {
    'id' : '5b6ef1e0f24411dfba8140403656340d',
    'name' : 'Kensing',
    'slug' : 'kensing',
    'campaign_url' : 'http://www.obsidianportal.com/campaigns/kensing'
   },
 'dynamic_sheet_template' : {
  'id' : '4a938f60f24211dfba7940403656340d',
  'name' : 'Chainsaws DnD 3.5',
  'slug' : 'chainsaw_dnd_35'
 },
 'dynamic_sheet' : {
  'race' : 'Half-Drow'
 },
 'description' : 'Level 30 wizard',
 'description_html' : '
Level 30 wizard
',
 'bio' : 'Has joined the party as a mentor',
 'bio_html' : '
Has joined the party as a mentor
',
 'is_player_character' : false,
 'author' : {
    'id' : '1b938f60f24211dfba7940403656340d',
    'username' : 'Micah',
    'profile_url' : 'http://www.obsidianportal.com/profile/Micah'
   },
 'created_at' : '2010-11-01T21:42:13Z',
 'updated_at' : '2010-11-20T18:00:00Z',
 'is_game_master_only' : false,
 'game_master_info' : 'Still is the bbeg',
 'game_master_info_html' : '
Still is the bbeg
'
}

Delete

URL: http://api.obsidianportal.com/v1/campaigns/ campaign_id/characters/id.format
HTTP Verb: DELETE
Requires Authentication: Yes
Required Parameters:

  • campaign_id - identifier - The ID of the campaign to retrieve a character from.
  • id - identifier - The ID of the character to delete.

Optional Parameters: None
Response Code: 204
Response Body: None

Example

Request 

 http://api.obsidianportal.com/v1/campaigns/5b6ef1e0f24411dfba8140403656340d/characters/e06993fcf24411dfba8140403656340d.json

Response

Still need help? Contact Us Contact Us