site/tags (GET)

Last updated
Save as PDF

Overview

Retrieve all tags

REST Method: GET
Method Access: public

Query Parameters

Name	Type	Description
to	string?	end date for type=date (ex: 2008-12-30) (default: now + 30 days)
from	string?	start date for type=date (ex: 2008-01-30) (default: now)
authenticate	bool?	Force authentication for request (default: false)
type	string?	type of the tag (text \| date \| user \| define) (default: all types)
q	string?	partial tag name to match (ex: tagprefix) (default none)
pages	bool?	show pages with each tag (default: false)

Return Codes

Name	Value	Description
OK	200	The request completed successfully
Bad Request	400	Invalid input parameter or request body
Forbidden	403	Read access to the page is required
Not Found	404	The requested page could not be found

Message Format

Output:

<tags count="{int}">
    <tag value="{text}" id="{int}" href="{uri}" count="{int}">
        <type>{date|define|text}</type>
        <uri>{uri}</uri>
        <title>{text}</title>
    </tag>
    <tag>
        ...
    </tag>
    ...
</tags>

Implementation Notes

Setting "pages" query parameter to true will return additional metadata of pages that contain specific tag.

Searching for tags of type "date" requires explicit "to" and "from" range, or only dates falling within a range of 30 days after the query will be returned.

Curl Code Sample: Retrieve List of All Tags

The following command retrieves a list of all tags throughout the site:

Sample Code

curl -u username:password -i http://mindtouch.address/@api/deki/site/tags

Sample Response from executing Code

Response indicating 3 tags exist.

Content-Type: application/xml

<tags count="3">
  <tag value="awesome" id="10" href="http://192.168.59.128/@api/deki/site/tags/10" count="1">
    <type>text</type>
    <uri>http://192.168.59.128/Special:Tags?tag=awesome</uri>
    <title>awesome</title>
  </tag>
  <tag value="real cool" id="11" href="http://192.168.59.128/@api/deki/site/tags/11" count="1">
    <type>text</type>
    <uri>http://192.168.59.128/Special:Tags?tag=real+cool</uri>
    <title>real cool</title>
  </tag>
  <tag value="groovy" id="12" href="http://192.168.59.128/@api/deki/site/tags/12" count="1">
    <type>text</type>
    <uri>http://192.168.59.128/Special:Tags?tag=groovy</uri>
    <title>groovy</title>
  </tag>
</tags>

Implementation notes

curl flags

-u: Provides external user authentication. Note that if anonymous access is available and authentication is not forced, this flag may be omitted.
-i: Outputs the HTTP response headers. Useful for debugging.