The following includes the details of how to interface with the forum topic records through the API.
01 Record field format
[hr]
[table]
[thead]
[tr]
[th]Name[/th]
[th]Type[/th]
[th]Details[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td][code]id[/code][/td]
[td]integer[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]title[/code][/td]
[td]string[/td]
[td][/td]
[/tr]
[tr]
[td][code]category_id[/code][/td]
[td]integer[/td]
[td][0,1,2][/td]
[/tr]
[tr]
[td][code]response_count[/code][/td]
[td]integer[/td]
[td][/td]
[/tr]
[tr]
[td][code]min_level[/code][/td]
[td]integer[/td]
[td]Corresponds to the level of user (API:Users).[/td]
[/tr]
[tr]
[td][code]is_deleted[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_sticky[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]is_locked[/code][/td]
[td]boolean[/td]
[td][/td]
[/tr]
[tr]
[td][code]creator_id[/code][/td]
[td]integer[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]updater_id[/code][/td]
[td]integer[/td]
[td]>0[/td]
[/tr]
[tr]
[td][code]created_at[/code][/td]
[td]timestamp[/td]
[td][/td]
[/tr]
[tr]
[td][code]updated_at[/code][/td]
[td]timestamp[/td]
[td][/td]
[/tr]
[/tbody]
[/table]
Category ID
[table]
[thead]
[tr]
[th]Value[/th]
[th]Description[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td]0[/td]
[td]General[/td]
[/tr]
[tr]
[td]1[/td]
[td]Tags[/td]
[/tr]
[tr]
[td]2[/td]
[td]Bugs & features[/td]
[/tr]
[/tbody]
[/table]
Min level
Min level is an integer when stored in the database, but is used and presented by Danbooru as an enum. Unrestricted access, i.e. a min level of 0, is "None". Every other ID is the user level, with it's name being the titlecase version of that level's name. For example, a min level for Gold members is 30, and is presented to the user as "Gold".
02 Associated attributes
[hr]
The following is the list of relations that can be included in the API results (see Help:Common URL Parameters for more info):
[table]
[thead]
[tr]
[th]Name[/th]
[th]Type[/th]
[th]Number[/th]
[th]Availability[/th]
[th]Details[/th]
[/tr]
[/thead]
[tbody]
[tr]
[td][code]creator[/code][/td]
[td]user[/td]
[td]single[/td]
[td]required[/td]
[td]User that created the forum topic.[/td]
[/tr]
[tr]
[td][code]updater[/code][/td]
[td]user[/td]
[td]single[/td]
[td]required[/td]
[td]User that last updated the forum topic.[/td]
[/tr]
[tr]
[td][code]original_post[/code][/td]
[td]forum post[/td]
[td]single[/td]
[td]required[/td]
[td]The first forum post of a forum topic.[/td]
[/tr]
[/tbody]
[/table]
03 Index
[hr]
Returns multiple forum topic records.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td]The default order is updated at descending.[/td]
[/tr]
[/tbody]
[/table]
Search attributes
Search parameters take the following format (see Help:Common URL Parameters for more info):
[code]
search[FIELD]=VALUE
[/code]
The following are the base fields along with their associated type. Check the syntax pages for all of the available variations.
- Number syntax
- [code]id[/code]
- [code]response_count[/code]
- [code]created_at[/code]
- [code]updated_at[/code]
- Text syntax
- [code]title[/code]
- Enum syntax
- [code]category[/code]
- Due to issue #6158, "Bugs & Features" is not searchable when using the search field [code]category[/code].
- Use [code]category_id[/code] and the value of [code]2[/code] instead.
- [code]min_level[/code]
- User syntax
- [code]creator[/code]
- [code]updater[/code]
- Boolean syntax
- [code]is_deleted[/code]
- [code]is_sticky[/code]
- [code]is_locked[/code]
- Chaining syntax
- [code]forum_posts[/code]
- [code]bulk_update_requests[/code]
- [code]tag_aliases[/code]
- [code]tag_implications[/code]
Special search parameters
The following are additional search fields.
- [code]status[/code] - The status of an attached BUR. Can be: pending, approved, rejected.
- [code]is_private[/code] - Shows topics that have a min level set or not (Help:Boolean Syntax).
- [code]is_read[/code] - Shows topics that have been read by the user or not (Help:Boolean Syntax).
Search order
Using the search parameter [code]order[/code] with one of the following values changes the order of the results.
- [code]sticky[/code] - Shows sticky topics first, sorted by updated at second.
- [code]id[/code] - Orders by ID desc.
- [code]custom[/code] - Help:Common URL Parameters
- In order to use this order, [code]search[id][/code] must also be set with a list of comma-separated IDs.
04 Show
[hr]
Returns a single forum topic record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]GET[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]read request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the forum topic ID.[/td]
[/tr]
[/tbody]
[/table]
05 Create
[hr]
Creates a single forum topic record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]POST[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[/tbody]
[/table]
Create parameters
Forum topic parameters take the following format (see Help:API Write Requests for more info):
[code]
forum_topic[FIELD]=VALUE
[/code]
- Required:
- [code]title[/code]
- [code]category_id[/code] - Can be: 0, 1, 2.
- [code]category[/code]
- Alternate to [code]category_id[/code].
- Can be
- Optional
- [code]original_post_attributes[body][/code] - DText that will be used to create a forum post entry at the same time.
- Is a hash value, so the final parameter format is [code]forum_topic[original_post_attributes][body][/code]
Restricted to Moderator+
- Optional
- [code]min_level[/code] - Can be: 0, 40, 50
- [code]is_sticky[/code]
- [code]is_locked[/code]
06 Update
[hr]
Updates a single forum topic record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]PUT/PATCH[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the forum topic ID.[/td]
[/tr]
[/tbody]
[/table]
Update parameters
Accepts the same parameters as the Create action. All parameters are optional.
Original post attributes
Besides those, the Update action also accepts the following additional optional parameters. These can be used to update the opening post of a forum topic if the user is capable of doing that (original poster or Moderator+).
- [code]original_post_attributes[id][/code] - The ID of the the first post on a topic.
- [code]original_post_attributes[body][/code] - The body of the first post on a topic.
The final format of these parameters look like the following:
[code]
forum_topic[original_post_attributes][id]=VALUE
[/code]
The [code]id[/code] parameter is required if updating the opening post, and it must match the actual ID of the opening post, i.e. it is not changeable.
07 Delete
[hr]
Deletes a single forum topic record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]DELETE[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics/$id.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the forum topic ID.
Restricted to Moderator+.[/td]
[/tr]
[/tbody]
[/table]
08 Undelete
[hr]
Undeletes a single forum topic record.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]POST[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics/$id/undelete.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[tr]
[td]Description[/td]
[td][code]$id[/code] is the forum topic ID.
Restricted to moderator+.[/td]
[/tr]
[/tbody]
[/table]
09 Mark all as read
[hr]
Marks every topic as being read.
[table]
[tbody]
[tr]
[td]HTTP Method[/td]
[td]POST[/td]
[/tr]
[tr]
[td]Base URL[/td]
[td][code]/forum_topics/mark_all_as_read.json[/code][/td]
[/tr]
[tr]
[td]Type[/td]
[td]write request[/td]
[/tr]
[/tbody]
[/table]
10 See also
[hr]
11 External links
[hr]
[table]
[tbody]
[tr]
[td]Controller[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/controllers/forum_topics_controller.rb>[/td]
[td][/td]
[/tr]
[tr]
[td]Model[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/models/forum_topic.rb>[/td]
[/tr]
[tr]
[td]Policy[/td]
[td]<https://github.com/danbooru/danbooru/blob/master/app/policies/forum_topic_policy.rb>[/td]
[/tr]
[/tbody]
[/table]