szurubooru/API.md

szurubooru uses REST API for all operations.

Table of contents

1. General rules

   • Authentication
   • Basic requests
   • File uploads
   • Error handling
   • Field selecting

2. API reference

   • Tag categories
     • Listing tag categories
     • Creating tag category
     • Updating tag category
     • Getting tag category
     • Deleting tag category
     • Setting default tag category
   • Tags
     • Listing tags
     • Creating tag
     • Updating tag
     • Getting tag
     • Deleting tag
     • Merging tags
     • Listing tag siblings
   • Posts
     • Listing posts
     • Creating post
     • Updating post
     • Getting post
     • Deleting post
     • Rating post
     • Adding post to favorites
     • Removing post from favorites
     • Getting featured post
     • Featuring post
   • Comments
     • Listing comments
     • Creating comment
     • Updating comment
     • Getting comment
     • Deleting comment
     • Rating comment
   • Users
     • Listing users
     • Creating user
     • Updating user
     • Getting user
     • Deleting user
   • Password reset
     • Password reset - step 1: mail request
     • Password reset - step 2: confirmation
   • Snapshots
     • Listing snapshots
   • Global info
     • Getting global info

3. Resources

   • User
   • Micro user
   • Tag category
   • Tag
   • Post
   • Note
   • Comment
   • Snapshot
   • Unpaged search result
   • Paged search result

4. Search

General rules

Authentication

Authentication is achieved by means of basic HTTP auth. For this reason, it is recommended to connect through HTTPS. There are no sessions, so every privileged request must be authenticated. Available privileges depend on the user's rank. The way how rank translates to privileges is defined in the server's configuration.

It is recommended to add ?bump-login GET parameter to the first request in a client "session" (where the definition of a session is up to the client), so that the user's last login time is kept up to date.

Basic requests

Every request must use Content-Type: application/json and Accept: application/json. An exception to this rule are requests that upload files.

File uploads

Requests that upload files must use multipart/form-data encoding. JSON metadata must then be included as field of name metadata, whereas files must be included as separate fields with names specific to each request type.

Alternatively, the server can download the files from the Internet on client's behalf. In that case, the request doesn't need to be specially encoded in any way. The files, however, should be passed as regular fields appended with Url suffix. For example, to download a file named content from http://example.com/file.jpg, the client should pass {"contentUrl":"http://example.com/file.jpg"} as part of the message body.

Error handling

All errors (except for unhandled fatal server errors) send relevant HTTP status code together with JSON of following structure:

{
    "title": "Generic title of error message, e.g. 'Not found'",
    "description": "Detailed description of what went wrong, e.g. 'User `rr-` not found."
}

Field selecting

For performance considerations, sometimes the client might want to choose the fields the server sends to it in order to improve the query speed. This customization is available for top-level fields of most of the resources. To choose the fields, the client should pass ?fields=field1,field2,... suffix to the query. This works regardless of the requesttype (GET, PUT etc.).

For example, to list posts while getting only their IDs and tags, the client should send a GET query like this:

GET /posts/?fields=id,tags

API reference

Depending on the deployment, the URLs might be relative to some base path such as /api/. Values denoted with diamond braces (<like this>) signify variable data.

Listing tag categories

• Request

  GET /tag-categories

• Output

  An unpaged search result, for which <resource> is a tag category resource.

• Errors

  • privileges are too low

• Description

  Lists all tag categories. Doesn't use paging.

  Note: independently, the server exports current tag category list snapshots to the data directory under tags.json name. Its purpose is to reduce the trips frontend needs to make when doing autocompletion, and ease caching. The data directory and its URL are controlled with data_dir and data_url variables in server's configuration.

Creating tag category

• Request

  POST /tag-categories

• Input

  {
      "name":  <name>,
      "color": <color>
  }
  

• Output

  A tag category resource.

• Errors

  • the name is used by an existing tag category (names are case insensitive)
  • the name is invalid or missing
  • the color is invalid or missing
  • privileges are too low

• Description

  Creates a new tag category using specified parameters. Name must match tag_category_name_regex from server's configuration. First category created becomes the default category.

Updating tag category

• Request

  PUT /tag-category/<name>

• Input

  {
      "name":  <name>,    // optional
      "color": <color>,   // optional
  }
  

• Output

  A tag category resource.

• Errors

  • the tag category does not exist
  • the name is used by an existing tag category (names are case insensitive)
  • the name is invalid
  • the color is invalid
  • privileges are too low

• Description

  Updates an existing tag category using specified parameters. Name must match tag_category_name_regex from server's configuration. All fields are optional - update concerns only provided fields.

Getting tag category

• Request

  GET /tag-category/<name>

• Output

  A tag category resource.

• Errors

  • the tag category does not exist
  • privileges are too low

• Description

  Retrieves information about an existing tag category.

Deleting tag category

• Request

  DELETE /tag-category/<name>

• Output

  {}
  

• Errors

  • the tag category does not exist
  • the tag category is used by some tags
  • the tag category is the last tag category available
  • privileges are too low

• Description

  Deletes existing tag category. The tag category to be deleted must have no usages.

Setting default tag category

• Request

  PUT /tag-category/<name>/default

• Input

  {}
  

• Output

  A tag category resource.

• Errors

  • the tag category does not exist
  • privileges are too low

• Description

  Sets given tag category as default. All new tags created manually or automatically will have this category.

Listing tags

• Request

  GET /tags/?page=<page>&pageSize=<page-size>&query=<query>

• Output

  A paged search result resource, for which <resource> is a tag resource.

• Errors

  • privileges are too low

• Description

  Searches for tags.

  Note: independently, the server exports current tag list snapshots to the data directory under tags.json name. Its purpose is to reduce the trips frontend needs to make when doing autocompletion, and ease caching. The data directory and its URL are controlled with data_dir and data_url variables in server's configuration.

  Anonymous tokens

  Same as name token.

  Named tokens

  <key>	Description
  name	having given name (accepts wildcards)
  category	having given category
  creation-date	created at given date
  creation-time	alias of creation-date
  last-edit-date	edited at given date
  last-edit-time	alias of last-edit-date
  edit-date	alias of last-edit-date
  edit-time	alias of last-edit-date
  usages	used in given number of posts
  usage-count	alias of usages
  post-count	alias of usages
  suggestion-count	with given number of suggestions
  implication-count	with given number of implications

  Sort style tokens

  <value>	Description
  random	as random as it can get
  name	A to Z
  category	category (A to Z)
  creation-date	recently created first
  creation-time	alias of creation-date
  last-edit-date	recently edited first
  last-edit-time	alias of creation-time
  edit-date	alias of creation-time
  edit-time	alias of creation-time
  usages	used in most posts first
  usage-count	alias of usages
  post-count	alias of usages
  suggestion-count	with most suggestions first
  implication-count	with most implications first

  Special tokens

  None.

Creating tag

• Request

  POST /tags

• Input

  {
      "names":        [<name1>, <name2>, ...],
      "category":     <category>,
      "implications": [<name1>, <name2>, ...],    // optional
      "suggestions":  [<name1>, <name2>, ...]     // optional
  }
  

• Output

  A tag resource.

• Errors

  • any name is used by an existing tag (names are case insensitive)
  • any name, implication or is invalid
  • category is invalid
  • no name was specified
  • implications or suggestions contain any item from names (e.g. there's a shallow cyclic dependency)
  • privileges are too low

• Description

  Creates a new tag using specified parameters. Names, suggestions and implications must match tag_name_regex from server's configuration. Category must exist and is the same as name field within <tag-category> resource. Suggestions and implications are optional. If specified implied tags or suggested tags do not exist yet, they will be automatically created. Tags created automatically have no implications, no suggestions, one name and their category is set to the first tag category found. If there are no tag categories established yet, an error will be thrown.

Updating tag

• Request

  PUT /tags/<name>

• Input

  {
      "names":        [<name1>, <name2>, ...],    // optional
      "category":     <category>,                 // optional
      "implications": [<name1>, <name2>, ...],    // optional
      "suggestions":  [<name1>, <name2>, ...]     // optional
  }
  

• Output

  A tag resource.

• Errors

  • the tag does not exist
  • any name is used by an existing tag (names are case insensitive)
  • any name, implication or suggestion name is invalid
  • category is invalid
  • implications or suggestions contain any item from names (e.g. there's a shallow cyclic dependency)
  • privileges are too low

• Description

  Updates an existing tag using specified parameters. Names, suggestions and implications must match tag_name_regex from server's configuration. Category must exist and is the same as name field within <tag-category> resource. If specified implied tags or suggested tags do not exist yet, they will be automatically created. Tags created automatically have no implications, no suggestions, one name and their category is set to the first tag category found. All fields are optional - update concerns only provided fields.

Getting tag

• Request

  GET /tag/<name>

• Output

  A tag resource.

• Errors

  • the tag does not exist
  • privileges are too low

• Description

  Retrieves information about an existing tag.

Deleting tag

• Request

  DELETE /tag/<name>

• Output

  {}
  

• Errors

  • the tag does not exist
  • the tag is used by some posts
  • privileges are too low

• Description

  Deletes existing tag. The tag to be deleted must have no usages.

Merging tags

• Request

  POST /tag-merge/

• Input

  {
      "remove":  <source-tag-name>,
      "mergeTo": <target-tag-name>
  }
  

• Output

  A tag resource containing the merged tag.

• Errors

  • the source or target tag does not exist
  • the source tag is the same as the target tag
  • privileges are too low

• Description

  Removes source tag and merges all of its usages to the target tag. Source tag properties such as category, tag relations etc. do not get transferred and are discarded. The target tag effectively remains unchanged with the exception of the set of posts it's used in.

Listing tag siblings

• Request

  GET /tag-siblings/<name>

• Output

  {
      "results": [
          {
              "tag": <tag>,
              "occurrences": <occurrence-count>
          },
          {
              "tag": <tag>,
              "occurrences": <occurrence-count>
          }
      ]
  }
  

  ...where <tag> is a tag resource.

• Errors

  • privileges are too low

• Description

  Lists siblings of given tag, e.g. tags that were used in the same posts as the given tag. occurrences field signifies how many times a given sibling appears with given tag. Results are sorted by occurrences count and the list is truncated to the first 50 elements. Doesn't use paging.

Listing posts

• Request

  GET /posts/?page=<page>&pageSize=<page-size>&query=<query>

• Output

  A paged search result resource, for which <resource> is a post resource.

• Errors

  • privileges are too low

• Description

  Searches for posts.

  Anonymous tokens

  Same as tag token.

  Named tokens

  <key>	Description
  id	having given post number
  tag	having given tag
  score	having given score
  uploader	uploaded by given user
  upload	alias of upload
  submit	alias of upload
  comment	commented by given user
  fav	favorited by given user
  tag-count	having given number of tags
  comment-count	having given number of comments
  fav-count	favorited by given number of users
  note-count	having given number of annotations
  feature-count	having been featured given number of times
  type	given type of posts. <value> can be either image, animation (or animated or anim), flash (or swf) or video (or webm).
  file-size	having given file size (in bytes)
  image-width	having given image width (where applicable)
  image-height	having given image height (where applicable)
  image-area	having given number of pixels (image width * image height)
  width	alias of image-width
  height	alias of image-height
  area	alias of image-area
  creation-date	posted at given date
  creation-time	alias of creation-date
  date	alias of creation-date
  time	alias of creation-date
  last-edit-date	edited at given date
  last-edit-time	alias of last-edit-date
  edit-date	alias of last-edit-date
  edit-time	alias of last-edit-date
  comment-date	commented at given date
  comment-time	alias of comment-date
  fav-date	last favorited at given date
  fav-time	alias of fav-date
  feature-date	featured at given date
  feature-time	alias of feature-time
  safety	having given safety. <value> can be either safe, sketchy (or questionable) or unsafe.
  rating	alias of safety

  Sort style tokens

  <value>	Description
  random	as random as it can get
  id	highest to lowest post number
  score	highest scored
  tag-count	with most tags
  comment-count	most commented first
  fav-count	loved by most
  note-count	with most annotations
  feature-count	most often featured
  file-size	largest files first
  image-width	widest images first
  image-height	tallest images first
  image-area	largest images first
  width	alias of image-width
  height	alias of image-height
  area	alias of image-area
  creation-date	newest to oldest (pretty much same as id)
  creation-time	alias of creation-date
  date	alias of creation-date
  time	alias of creation-date
  last-edit-date	like creation-date, only looks at last edit time
  last-edit-time	alias of last-edit-date
  edit-date	alias of last-edit-date
  edit-time	alias of last-edit-date
  comment-date	recently commented by anyone
  comment-time	alias of comment-date
  fav-date	recently added to favorites by anyone
  fav-time	alias of fav-date
  feature-date	recently featured
  feature-time	alias of feature-time

  Special tokens

  <value>	Description
  liked	posts liked by currently logged in user
  disliked	posts disliked by currently logged in user
  fav	posts added to favorites by currently logged in user
  tumbleweed	posts with score of 0, without comments and without favorites

Creating post

• Request

  POST /posts/

• Input

  {
      "tags":         [<tag1>, <tag2>, <tag3>],
      "safety":       <safety>,
      "source":       <source>,                     // optional
      "relations":    [<post1>, <post2>, <post3>],  // optional
      "notes":        [<note1>, <note2>, <note3>],  // optional
      "flags":        [<flag1>, <flag2>],           // optional
      "anonymous":    <anonymous>                   // optional
  }
  

• Files

  • content - the content of the content.
  • thumbnail - the content of custom thumbnail (optional).

• Output

  A post resource.

• Errors

  • tags have invalid names
  • safety, notes or flags are invalid
  • relations refer to non-existing posts
  • privileges are too low

• Description

  Creates a new post. If specified tags do not exist yet, they will be automatically created. Tags created automatically have no implications, no suggestions, one name and their category is set to the first tag category found. Safety must be any of "safe", "sketchy" or "unsafe". Relations must contain valid post IDs. <flag> currently can be only "loop" to enable looping for video posts. Sending empty thumbnail will cause the post to use default thumbnail. If anonymous is set to truthy value, the uploader name won't be recorded (privilege verification still applies; it's possible to disallow anonymous uploads completely from config.) All fields are optional - update concerns only provided fields. For details how to pass content and thumbnail, see file uploads for details.

Updating post

• Request

  PUT /post/<id>

• Input

  {
      "tags":         [<tag1>, <tag2>, <tag3>],     // optional
      "safety":       <safety>,                     // optional
      "source":       <source>,                     // optional
      "relations":    [<post1>, <post2>, <post3>],  // optional
      "notes":        [<note1>, <note2>, <note3>],  // optional
      "flags":        [<flag1>, <flag2>]            // optional
  }
  

• Files

  • content - the content of the content (optional).
  • thumbnail - the content of custom thumbnail (optional).

• Output

  A post resource.

• Errors

  • tags have invalid names
  • safety, notes or flags are invalid
  • relations refer to non-existing posts
  • privileges are too low

• Description

  Updates existing post. If specified tags do not exist yet, they will be automatically created. Tags created automatically have no implications, no suggestions, one name and their category is set to the first tag category found. Safety must be any of "safe", "sketchy" or "unsafe". Relations must contain valid post IDs. <flag> currently can be only "loop" to enable looping for video posts. Sending empty thumbnail will reset the post thumbnail to default. For details how to pass content and thumbnail, see file uploads for details.

Getting post

• Request

  GET /post/<id>

• Output

  A post resource.

• Errors

  • the post does not exist
  • privileges are too low

• Description

  Retrieves information about an existing post.

Deleting post

• Request

  DELETE /post/<id>

• Output

  {}
  

• Errors

  • the post does not exist
  • privileges are too low

• Description

  Deletes existing post. Related posts and tags are kept.

Rating post

• Request

  PUT /post/<id>/score

• Input

  {
      "score": <score>
  }
  

• Output

  A post resource.

• Errors

  • post does not exist
  • score is invalid
  • privileges are too low

• Description

  Updates score of authenticated user for given post. Valid scores are -1, 0 and 1.

Adding post to favorites

• Request

  POST /post/<id>/favorite

• Output

  A post resource.

• Errors

  • post does not exist
  • privileges are too low

• Description

  Marks the post as favorite for authenticated user.

Removing post from favorites

• Request

  DELETE /post/<id>/favorite

• Output

  A post resource.

• Errors

  • post does not exist
  • privileges are too low

• Description

  Unmarks the post as favorite for authenticated user.

Getting featured post

• Request

  GET /featured-post

• Output

  A post resource.

• Errors

  • privileges are too low

• Description

  Retrieves the post that is currently featured on the main page in web client. If no post is featured, <post> is null and snapshots array is empty. Note that this method exists mostly for compatibility with setting featured post - most of times, you'd want to use query global info which contains more information.

Featuring post

• Request

  POST /featured-post

• Input

  {
      "id": <post-id>
  }
  

• Output

  A post resource.

• Errors

  • privileges are too low
  • trying to feature a post that is currently featured

• Description

  Features a post on the main page in web client.

Listing comments

• Request

  GET /comments/?page=<page>&pageSize=<page-size>&query=<query>

• Output

  A paged search result resource, for which <resource> is a comment resource.

• Errors

  • privileges are too low

• Description

  Searches for comments.

  Anonymous tokens

  Same as text token.

  Named tokens

  <key>	Description
  id	specific comment ID
  post	specific post ID
  user	created by given user (accepts wildcards)
  author	alias of user
  text	containing given text (accepts wildcards)
  creation-date	created at given date
  creation-time	alias of creation-date
  last-edit-date	whose most recent edit date matches given date
  last-edit-time	alias of last-edit-date
  edit-date	alias of last-edit-date
  edit-time	alias of last-edit-date

  Sort style tokens

  <value>	Description
  random	as random as it can get
  user	author name, A to Z
  author	alias of user
  post	post ID, newest to oldest
  creation-date	newest to oldest
  creation-time	alias of creation-date
  last-edit-date	recently edited first
  last-edit-time	alias of last-edit-date
  edit-date	alias of last-edit-date
  edit-time	alias of last-edit-date

  Special tokens

  None.

Creating comment

• Request

  POST /comments/

• Input

  {
      "text":     <text>,
      "postId":   <post-id>
  }
  

• Output

  A comment resource.

• Errors

  • the post does not exist
  • comment text is empty
  • privileges are too low

• Description

  Creates a new comment under given post.

Updating comment

• Request

  PUT /comment/<id>

• Input

  {
      "text": <new-text>      // mandatory
  }
  

• Output

  A comment resource.

• Errors

  • the comment does not exist
  • new comment text is empty
  • privileges are too low

• Description

  Updates an existing comment text.

Getting comment

• Request

  GET /comment/<id>

• Output

  A comment resource.

• Errors

  • the comment does not exist
  • privileges are too low

• Description

  Retrieves information about an existing comment.

Deleting comment

• Request

  DELETE /comment/<id>

• Output

  {}
  

• Errors

  • the comment does not exist
  • privileges are too low

• Description

  Deletes existing comment.

Rating comment

• Request

  PUT /comment/<id>/score

• Input

  {
      "score": <score>
  }
  

• Output

  A comment resource.

• Errors

  • comment does not exist
  • score is invalid
  • privileges are too low

• Description

  Updates score of authenticated user for given comment. Valid scores are -1, 0 and 1.

Listing users

• Request

  GET /users/?page=<page>&pageSize=<page-size>&query=<query>

• Output

  A paged search result resource, for which <resource> is a user resource.

• Errors

  • privileges are too low

• Description

  Searches for users.

  Anonymous tokens

  Same as name token.

  Named tokens

  <key>	Description
  name	having given name (accepts wildcards)
  creation-date	registered at given date
  creation-time	alias of creation-date
  last-login-date	whose most recent login date matches given date
  last-login-time	alias of last-login-date
  login-date	alias of last-login-date
  login-time	alias of last-login-date

  Sort style tokens

  <value>	Description
  random	as random as it can get
  name	A to Z
  creation-date	newest to oldest
  creation-time	alias of creation-date
  last-login-date	recently active first
  last-login-time	alias of last-login-date
  login-date	alias of last-login-date
  login-time	alias of last-login-date

  Special tokens

  None.

Creating user

• Request

  POST /users

• Input

  {
      "name": <user-name>,
      "password": <user-password>,
      "email": <email>,               // optional
      "rank": <rank>,                 // optional
      "avatarStyle": <avatar-style>   // optional
  }
  

• Files

  • avatar - the content of the new avatar (optional).

• Output

  A user resource.

• Errors

  • a user with such name already exists (names are case insensitive)
  • either user name, password, email or rank are invalid
  • the user is trying to update their or someone else's rank to higher than their own
  • avatar is missing for manual avatar style
  • privileges are too low

• Description

  Creates a new user using specified parameters. Names and passwords must match user_name_regex and password_regex from server's configuration, respectively. Email address, rank and avatar fields are optional. Avatar style can be either gravatar or manual. manual avatar style requires client to pass also avatar file - see file uploads for details. If the rank is empty and the user happens to be the first user ever created, become an administrator, whereas subsequent users will be given the rank indicated by default_rank in the server's configuration.

Updating user

• Request

  PUT /user/<name>

• Input

  {
      "name": <user-name>,            // optional
      "password": <user-password>,    // optional
      "email": <email>,               // optional
      "rank": <rank>,                 // optional
      "avatarStyle": <avatar-style>   // optional
  }
  

• Files

  • avatar - the content of the new avatar (optional).

• Output

  A user resource.

• Errors

  • the user does not exist
  • a user with new name already exists (names are case insensitive)
  • either user name, password, email or rank are invalid
  • the user is trying to update their or someone else's rank to higher than their own
  • avatar is missing for manual avatar style
  • privileges are too low

• Description

  Updates an existing user using specified parameters. Names and passwords must match user_name_regex and password_regex from server's configuration, respectively. All fields are optional - update concerns only provided fields. To update last login time, see authentication. Avatar style can be either gravatar or manual. manual avatar style requires client to pass also avatar file - see file uploads for details.

Getting user

• Request

  GET /user/<name>

• Output

  A user resource.

• Errors

  • the user does not exist
  • privileges are too low

• Description

  Retrieves information about an existing user.

Deleting user

• Request

  DELETE /user/<name>

• Output

  {}
  

• Errors

  • the user does not exist
  • privileges are too low

• Description

  Deletes existing user.

Password reset - step 1: mail request

• Request

  GET /password-reset/<email-or-name>

• Output

  {}
  

• Errors

  • the user does not exist
  • the user hasn't provided an email address

• Description

  Sends a confirmation email to given user. The email contains link containing a token. The token cannot be guessed, thus using such link proves that the person who requested to reset the password also owns the mailbox, which is a strong indication they are the rightful owner of the account.

Password reset - step 2: confirmation

• Request

  POST /password-reset/<email-or-name>

• Input

  {
      "token": <token-from-email>
  }
  

• Output

  {
      "password": <new-password>
  }
  

• Errors

  • the token is missing
  • the token is invalid
  • the user does not exist

• Description

  Generates a new password for given user. Password is sent as plain-text, so it is recommended to connect through HTTPS.

Listing snapshots

• Request

  GET /snapshots/?page=<page>&pageSize=<page-size>&query=<query>

• Output

  A paged search result resource, for which <resource> is a snapshot resource.

• Errors

  • privileges are too low

• Description

  Lists recent resource snapshots.

  Anonymous tokens

  Not supported.

  Named tokens

  <key>	Description
  type	involving given resource type
  id	involving given resource id
  date	created at given date
  time	alias of date
  operation	changed, created or deleted
  user	name of the user that created given snapshot

  Sort style tokens

  None. The snapshots are always sorted by creation time.

  Special tokens

  None.

Getting global info

• Request

  GET /info

• Output

  {
      "postCount": <post-count>,
      "diskUsage": <disk-usage>,  // in bytes
      "featuredPost": <featured-post>,
      "featuringTime": <time>,
      "featuringUser": <user>,
      "serverTime": <server-time>
  }
  

• Description

  Retrieves simple statistics. <featured-post> is null if there is no featured post yet. <server-time> is pretty much the same as the Date HTTP field, only formatted in a manner consistent with other dates.

Resources

User

Description

A single user.

Structure

{
    "name":              <name>,
    "email":             <email>,
    "rank":              <rank>,
    "lastLoginTime":     <last-login-time>,
    "creationTime":      <creation-time>,
    "avatarStyle":       <avatar-style>,
    "avatarUrl":         <avatar-url>,
    "commentCount":      <comment-count>,
    "uploadedPostCount": <uploaded-post-count>,
    "likedPostCount":    <liked-post-count>,
    "dislikedPostCount": <disliked-post-count>,
    "faoritevPostCount": <favorite-post-count>
}

Field meaning

• <name>: the user name.

• <email>: the user email. It is available only if the request is authenticated by the same user, or the authenticated user can change the email. If it's unavailable, the server returns false. If the user hasn't specified an email, the server returns null.

• <rank>: the user rank, which effectively affects their privileges.

  Possible values:

  • "restricted": restricted user
  • "regular": regular user
  • "power": power user
  • "moderator": moderator
  • "administrator": administrator

• <last-login-time>: the last login time, formatted as per RFC 3339.

• <creation-time>: the user registration time, formatted as per RFC 3339.

• <avatarStyle>: how to render the user avatar.

  Possible values:

  • "gravatar": the user uses Gravatar.
  • "manual": the user has uploaded a picture manually.

• <avatarUrl>: the URL to the avatar.

• <comment-count>: number of comments.

• <uploaded-post-count>: number of uploaded posts.

• <liked-post-count>: nubmer of liked posts. It is available only if the request is authenticated by the same user. If it's unavailable, the server returns false.

• <disliked-post-count>: number of disliked posts. It is available only if the request is authenticated by the same user. If it's unavailable, the server returns false.

• <favorite-post-count>: number of favorited posts.

Micro user

Description

A user resource stripped down to name and avatarUrl fields.

Tag category

Description

A single tag category. The primary purpose of tag categories is to distinguish certain tag types (such as characters, media type etc.), which improves user experience.

Structure

{
    "name":  <name>,
    "color": <color>,
    "usages": <usages>
    "default": <is-default>,
    "snapshots": [
        <snapshot>,
        <snapshot>,
        <snapshot>
    ]
}

Field meaning

• <name>: the category name.
• <color>: the category color.
• <usages>: how many tags is the given category used with.
• <is-default>: whether the tag category is the default one.
• <snapshot>: a snapshot resource that contains the tag category's earlier versions.

Tag

Description

A single tag. Tags are used to let users search for posts.

Structure

{
    "names":        <names>,
    "category":     <category>,
    "implications": <implications>,
    "suggestions":  <suggestions>,
    "creationTime": <creation-time>,
    "lastEditTime": <last-edit-time>,
    "usages":       <usage-count>,
    "snapshots": [
        <snapshot>,
        <snapshot>,
        <snapshot>
    ]
}

Field meaning

• <names>: a list of tag names (aliases). Tagging a post with any name will automatically assign the first name from this list.
• <category>: the name of the category the given tag belongs to.
• <implications>: a list of implied tag names. Implied tags are automatically appended by the web client on usage.
• <suggestions>: a list of suggested tag names. Suggested tags are shown to the user by the web client on usage.
• <creation-time>: time the tag was created, formatted as per RFC 3339.
• <last-edit-time>: time the tag was edited, formatted as per RFC 3339.
• <usage-count>: the number of posts the tag was used in.
• <snapshot>: a snapshot resource that contains the tag's earlier versions.

Post

Description

One file together with its metadata posted to the site.

Structure

{
    "id":                 <id>,
    "creationTime":       <creation-time>,
    "lastEditTime":       <last-edit-time>,
    "safety":             <safety>,
    "source":             <source>,
    "type":               <type>,
    "checksum":           <checksum>,
    "canvasWidth":        <canvas-width>,
    "canvasHeight":       <canvas-height>,
    "contentUrl":         <content-url>,
    "thumbnailUrl":       <thumbnail-url>,
    "flags":              <flags>,
    "tags":               <tags>,
    "relations":          <relations>,
    "notes":              <notes>,
    "user":               <user>,
    "score":              <score>,
    "ownScore":           <own-score>,
    "ownFavorite":        <own-favorite>,
    "tagCount":           <tag-count>,
    "favoriteCount":      <favorite-count>,
    "commentCount":       <comment-count>,
    "noteCount":          <note-count>,
    "featureCount":       <feature-count>,
    "lastFeatureTime":    <last-feature-time>,
    "favoritedBy":        <favorited-by>,
    "hasCustomThumbnail": <has-custom-thumbnail>,
    "mimeType":           <mime-type>
    "snapshots": [
        <snapshot>,
        <snapshot>,
        <snapshot>
    ],
    "comments": {
        <comment>,
        <comment>,
        <comment>
    }
}

Field meaning

• <id>: the post identifier.

• <creation-time>: time the tag was created, formatted as per RFC 3339.

• <last-edit-time>: time the tag was edited, formatted as per RFC 3339.

• <safety>: whether the post is safe for work.

  Available values:

  • "safe"
  • "sketchy"
  • "unsafe"

• <source>: where the post was grabbed form, supplied by the user.

• <type>: the type of the post.

  Available values:

  • "image" - plain image.
  • "animation" - animated image (GIF).
  • "video" - WEBM video.
  • "flash" - Flash animation / game.
  • "youtube" - Youtube embed.

• <checksum>: the file checksum. Used in snapshots to signify changes of the post content.

• <canvas-width> and <canvas-height>: the original width and height of the post content.

• <content-url>: where the post content is located.

• <thumbnail-url>: where the post thumbnail is located.

• <flags>: various flags such as whether the post is looped, represented as array of plain strings.

• <tags>: list of tag names the post is tagged with.

• <relations>: a list of related post IDs. Links to related posts are shown to the user by the web client.

• <notes>: a list of post annotations, serialized as list of note resources.

• <user>: who created the post, serialized as micro user resource.

• <score>: the collective score (+1/-1 rating) of the given post.

• <own-score>: the score (+1/-1 rating) of the given post by the authenticated user.

• <own-favorite>: whether the authenticated user has given post in their favorites.

• <tag-count>: how many tags the post is tagged with

• <favorite-count>: how many users have the post in their favorites

• <comment-count>: how many comments are filed under that post

• <note-count>: how many notes the post has

• <feature-count>: how many times has the post been featured.

• <last-feature-time>: the last time the post was featured, formatted as per RFC 3339.

• <favorited-by>: list of users, serialized as micro user resources.

• <has-custom-thumbnail>: whether the post uses custom thumbnail.

• <mime-type>: subsidiary to <type>, used to tell exact content format; useful for <video> tags for instance.

• <snapshot>: a snapshot resource that contains the post's earlier versions.

• <comment>: a comment resource for given post.

Note

Description

A text annotation rendered on top of the post.

Structure

{
    "polygon": <list-of-points>,
    "text":    <text>,
}

Field meaning

• <list-of-points>: where to draw the annotation. Each point must have coordinates within 0 to 1. For example, [[0,0],[0,1],[1,1],[1,0]] will draw the annotation on the whole post, whereas [[0,0],[0,0.5],[0.5,0.5],[0.5,0]] will draw it inside the post's upper left quarter.
• <text>: the annotation text. The client should render is as Markdown.

Comment

Description

A comment under a post.

Structure

{
    "id":           <id>,
    "postId":       <post-id>,
    "user":         <author>
    "text":         <text>,
    "creationTime": <creation-time>,
    "lastEditTime": <last-edit-time>,
    "score":        <score>,
    "ownScore":     <own-score>
}

Field meaning

• <id>: the comment identifier.
• <post-id>: an id of the post the comment is for.
• <text>: the comment content. The client should render is as Markdown.
• <author>: a micro user resource the comment is created by.
• <creation-time>: time the comment was created, formatted as per RFC 3339.
• <last-edit-time>: time the comment was edited, formatted as per RFC 3339.
• <score>: the collective score (+1/-1 rating) of the given comment.
• <own-score>: the score (+1/-1 rating) of the given comment by the authenticated user.

Snapshot

Description

A snapshot is a version of a database resource.

Structure

{
    "operation":    <operation>,
    "type":         <resource-type>
    "id":           <resource-id>,
    "user":         <user-name>,
    "data":         <data>,
    "earlier-data": <earlier-data>,
    "time":         <time>
}

Field meaning

• <operation>: what happened to the resource.

  The value can be either of values below:

  • "created" - the resource has been created
  • "modified" - the resource has been modified
  • "deleted" - the resource has been deleted

• <resource-type> and <resource-id>: the resource that was changed.

  The values are correlated as per table below:

  <resource-type>	<resource-id>
  "tag"	first tag name at given time
  "tag_category"	tag category name at given time
  "post"	post ID

• <user-name>: name of the user who has made the change.

• <data>: the snapshot data.

  The value can be either of structures below:

  • Tag category snapshot data (<resource-type> = "tag")

    Example

    {
        "name":  "character",
        "color": "#FF0000",
        "default": false
    }
    

  • Tag snapshot data (<resource-type> = "tag")

    Example

    {
        "names":        ["tag1", "tag2", "tag3"],
        "category":     "plain",
        "implications": ["imp1", "imp2", "imp3"],
        "suggestions":  ["sug1", "sug2", "sug3"]
    }
    

  • Post snapshot data (<resource-type> = "post")

    Example

    {
        "source": "http://example.com/",
        "safety": "safe",
        "checksum": "deadbeef",
        "tags": ["tag1", "tag2"],
        "relations": [1, 2],
        "notes": [<note1>, <note2>, <note3>],
        "flags": ["loop"],
        "featured": false
    }
    

• <earlier-data>: <data> field from the last snapshot of the same resource. This allows the client to create visual diffs for any given snapshot without the need to know any other snapshots for a given resource.

• <time>: when the snapshot was created (i.e. when the resource was changed), formatted as per RFC 3339.

Unpaged search result

Description

A result of search operation that doesn't involve paging.

Structure

{
    "results": [
        <resource>,
        <resource>,
        <resource>
    ]
}

Field meaning

• <resource>: any resource - which exactly depends on the API call. For details on this field, check the documentation for given API call.

Paged search result

Description

A result of search operation that involves paging.

Structure

{
    "query":    <query>, // same as in input
    "page":     <page>,  // same as in input
    "pageSize": <page-size>,
    "total":    <total-count>,
    "results": [
        <resource>,
        <resource>,
        <resource>
    ]
}

Field meaning

• <query>: the query passed in the original request that contains standard search query.
• <page>: the page number, passed in the original request.
• <page-size>: number of records on one page.
• <total-count>: how many resources were found. To get the page count, divide this number by <page-size>.
• <resource>: any resource - which exactly depends on the API call. For details on this field, check the documentation for given API call.

Search

Search queries are built of tokens that are separated by spaces. Each token can be of following form:

Syntax	Token type	Description
<value>	anonymous tokens	basic filters
<key>:<value>	named tokens	advanced filters
sort:<style>	sort style tokens	sort the results
special:<value>	special tokens	filters usually tied to the logged in user

Most of anonymous and named tokens support ranged and composite values that take following form:

<value>	Description
a,b,c	will show things that satisfy either a, b or c.
1..	will show things that are equal to or greater than 1.
..4	will show things that are equal to at most 4.
1..4	will show things that are equal to 1, 2, 3 or 4.

Ranged values can be also supplied by appending -min or -max to the key, for example like this: score-min:1.

Date/time values can be of following form:

• today
• yesterday
• <year>
• <year>-<month>
• <year>-<month>-<day>

Some fields, such as user names, can take wildcards (*).

Example

Searching for posts with following query:

sea -fav-count:8.. type:swf uploader:Pirate

will show flash files tagged as sea, that were liked by seven people at most, uploaded by user Pirate.