To create new tags and assign tags to specific items, use the /pathways/api/item/[id]/tag interface.

• To retrieve tags that contain a specific string, use GET /pathways/api/suggest/[tag-prefix]. For example, the following request retrieves tags that start with “port”: GET /pathways/api/suggest/port?format=xml.
• To retrieve a weighted tag cloud, use GET /pathways/api/tags/[viewid] where [viewid] is “my” for the current user's tags, “ev” for everyone's tags, or a custom view ID.
• To retrieve tags applied to a specific item, use GET /pathways/api/item/[id]/tags. For example, the following request retrieves tags associated with the portal item with ID 1985: GET /pathways/api/item/PTPORTAL/18_1985/tags?format=XML. The response provides a list of tags:

  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagList xmlns:soc="http://social.bea.com/pathways">
      <tag>
          <count>1</count>
          <isAppliedByCurrentUser>true</isAppliedByCurrentUser>
          <normalizedCount>9</normalizedCount>
          <value>phenomenon</value>
      </tag>
      <tag>
          <count>1</count>
          <isAppliedByCurrentUser>true</isAppliedByCurrentUser>
          <normalizedCount>9</normalizedCount>
          <value>sudden</value>
      </tag>
  </soc:PTagList>
  

• To add a tag from a specific item, use POST /pathways/api/item/[id]/tag as shown in the example below. The following request creates tags ‘foo’ and ‘bar’ and assigns them to portal document 210:

  POST /pathways/api/item/PTPORTAL/1_210/tags
  CSP-Session-Token: 1|1207243836|0d6PFr/Z+mRrarbn9uhZJyYL2uI=
  Host: smahendr03.amer.bea.com:11990
  Accept-Language: en-us
  ACCEPT: application/xml
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagList xmlns:soc="http://social.bea.com/pathways">
      <tag>
          <value>foo</value>
      </tag>
      <tag>
          <value>bar</value>
      </tag>
  </soc:PTagList>
  

  The response confirms that the request was successful:

  HTTP/1.1 201 Created
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagList xmlns:soc="http://social.bea.com/pathways">
      <tag>
          <value>foo</value>
      </tag>
      <tag>
          <value>bar</value>
      </tag>
  </soc:PTagList>
  

  This same request could be used with the HTTP DELETE method to remove these tags from the item. The successful response code would be 202 Accepted instead of 201 Created.
• To delete a tag from multiple items within a specific view, use DELETE /pathways/api/tag/[viewid]/[tag] where [viewid] is “my” for the current user's tags, “ev” for everyone's tags, or a custom view ID; and [tag] is the tag value.

  Users with WRITE_APPLICATION capability can delete tags that they applied or tags applied by other users. For example, an administrator could remove all tags corresponding to "acquisition" for everyone (the "ev" view) or, more narrowly, for another group view, or for a specifically identified user (“custom/[ptsource]/[userid]”).

  For example, the following request deletes tag ‘foo’ from all items in view ‘bar’: DELETE /pathways/api/tag/bar/foo.

  The response confirms that the request was successful:

  HTTP/1.1 202 Accepted
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagViewStatus xmlns:soc="http://social.bea.com/pathways">
      <value>foo</value>
      <appliedItem>PTPORTAL:18:201</appliedItem>
      <appliedItem>PTPORTAL:18:203</appliedItem>
  </soc:PTagViewStatus>
  

  In the example above, ‘foo’ was removed from Knowledge Directory items with object IDs of 201 and 203.
• To rename a tag applied to multiple items within a specific view, use PUT /pathways/api/tag/[viewid]/[tag] where [viewid] is “my” for the current user's tags, “ev” for everyone's tags, or a custom view ID; and [tag] is the tag value.
  Important: The "appliedItem" elements are returned in the response to the 'rename' request, but they should not be passed when making the request. If you add the “appliedItem” element to the request, an error is produced indicating how the call should be invoked.

  Users with WRITE_APPLICATION capability can rename tags that they applied or tags applied by other users. For example, an administrator could rename all “HR” tags to “human resources” for everyone (the "ev" view) or, more narrowly, for another group view, or for a specifically identified user (“custom/[ptsource]/[userid]”).

  For example, the following request renames tag ‘foo’ to ‘bar’ from all items in view ‘ev’:

  PUT /pathways/api/tag/ev/foo
  CSP-Session-Token: 1|1207243836|0d6PFr/Z+mRrarbn9uhZJyYL2uI=
  Host: smahendr03.amer.bea.com:11990
  Accept-Language: en-us
  ACCEPT: application/xml
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagViewStatus xmlns:soc="http://social.bea.com/pathways">
      <value>bar</value>
  </soc:PTagViewStatus>
  

  The response confirms that the request was successful:

  HTTP/1.1 202 Accepted
  
  <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
  <soc:PTagViewStatus xmlns:soc="http://social.bea.com/pathways">
      <value>bar</value>
      <appliedItem>PTPORTAL:18:201</appliedItem>
      <appliedItem>PTPORTAL:18:203</appliedItem>
  </soc:PTagViewStatus>
  

  In the example above, the tag ‘bar’ replaced the tag ‘foo’ for Knowledge Directory items with object IDs of 201 and 203.