Fanboi Channel

API documentation

Last updated

Retrieving boards #api-boards

GET /api/1.0/boards/

Use this endpoint to retrieve a list of boards. The data retrieved from this endpoint is rarely updated and should be safe to cache. It is possible to include recent topics and its recent posts with query strings (see also #api-board and #api-topic), doing so with this API is not recommended as it will put extra loads on the server.

Response

Array containing #api-board.

Retrieving a board #api-board

GET /api/1.0/boards/{api-board.slug}/

Use this endpoint to retrieve any individual board. By default this endpoint will not include topics and recent posts in the response. It is possible to instruct the API to include those data with query strings listed below. Passing both ?topics=1&posts=1 will make the API effectively returning the same data as board's "Recent topics" page.

Query string Description
?topics=1 Include the recent 10 topics in a topics object.
?posts=1 Include the recent 30 posts in a posts object. Only if topics is present.

Response

Object containing the fields as listed below. Unicode strings are escaped in actual response.

Field Type Description
type String

The type of API object. The value is always "board".

"type":"board"
id Integer

Internal ID for the board.

"id":1
agreements String

A Markdown-formatted agreements for using the board.

"agreements":"* ห้ามมีเนื้อหาเกี่ยวข้องกับการเมืองหรือสถาบันพระมหากษัตริย์โดยเด็ดขาด"
description String

The description of the board.

"description":"บอร์ดอิสระสำหรับพูดคุยเรื่องใดก็ได้ที่หมวดที่มีอยู่ไม่ครอบคลุม"
settings Object

The settings for the board. Available options are:

  • post_delayInteger, number of seconds user should wait before posting a new post.
  • use_identBoolean, whether to generate ID for each post in the board.
  • nameString, the default name for each post in case user did not provide a name.
  • max_postsInteger, number of maximum posts per each topic in the board.
"settings":{
"post_delay":10,
"use_ident":true,
"name":"Nameless Fanboi",
"max_posts":1000
}
slug String

The identity slug of the board.

"slug":"lounge"
status String

Status string whether the board is still active or not. Available values are:

  • open — the board is postable.
  • restricted — the board is postable but no new topics can be made.
  • locked — the board could not be posted.
  • archived — the board could not be posted and is no longer listed in board list.
"status":"open"
title String

The title of the board.

"title":"Lounge"
path String

The path to this resource.

"path":"/api/1.0/boards/lounge/"

Creating new topic in a board #api-board-topics-new

POST /api/1.0/boards/{api-board.slug}/topics/

Use this endpoint to create a new topic in a specific board. Please note that this API will enqueue the topic with the global posting queue and will not guarantee that the topic will be successfully posted. To retrieve the status of topic creation, please see #api-task.

Parameters Type Description
title String Title of the topic. From 5 to 200 characters.
body String Content of the topic. From 5 to 4,000 characters.

Response

Either an #api-task or an #api-error.

Retrieving topics associated to a board #api-board-topics

GET /api/1.0/boards/{api-board.slug}/topics/

Use this endpoint to retrieve a list of topics associated to the specific board. By default this API will return the same data as board's "All topics" page which includes open topic and topic that are closed (locked and archived) within 1 week of last posted date. It is also possible to include recent posts with query string but doing so with this API is not recommended.

Query string Description
?board=1 Include the board in a board object.
?posts=1 Include the recent 30 posts in a posts object.

Response

Array containing #api-topic.

Retrieving a topic #api-topic

GET /api/1.0/topics/{api-topic.id}/

Use this endpoint to retrieve any individual topic. This endpoint by default will not include any posts but it is possible to instruct the API to include them using query string. Posts retrieved as part of this API is limited to the recent 30 posts. For retrieving a full list of posts, see #api-topic-posts and #api-topic-posts-scoped.

Query string Description
?board=1 Include the board in a board object.
?posts=1 Include the recent 30 posts in a posts object.

Response

Field Type Description
type String

The type of API object. The value is always "topic".

"type":"topic"
id Integer

Internal ID for the topic.

"id":1
board_id Integer

Internal ID of a board the topic is associated with.

"board_id":1
bumped_at String

ISO 8601-formatted datetime of when the topic was last bumped to top of the board.

"bumped_at":"2014-05-07T07:22:01.831981-07:00"
created_at String

ISO 8601-formatted datetime of when the topic was created.

"created_at":"2013-02-06T16:45:20.275693-08:00"
post_count Integer

Number of posts in the topic.

"post_count":693
posted_at String

ISO 8601-formatted datetime of when a new post was made to the topic regardless of bump status.

"posted_at":"2014-05-07T07:52:27.700932-07:00"
status String

Status string whether the topic is still active or not. Available values are:

  • open — the topic is active and postable.
  • locked — the topic has been locked by moderator and could not be posted.
  • archived — the topic has been automatically archived and could not be posted.
"status":"open"
title String

The title of the topic entered by the user in new topic form.

"title":"ยินดีต้อนรับเข้าสู่ Fanboi Channel 2.0"
path String

The path to this resource.

"path":"/api/1.0/topics/1/"

Creating new post in a topic #api-topic-posts-new

POST /api/1.0/topics/{api-topic.id}/posts/

Use this endpoint to create a new post in a specific topic (i.e. post a reply). Please note that this API will enqueue the post with the global posting queue and will not guarantee that the post will be successful. To retrieve the status of the post, please see #api-task.

Parameters Type Description
body String Content of the topic. From 5 to 4,000 characters.
bumped Boolean A flag whether the post should bump the topic to top of the board.

Response

Either an #api-task or an #api-error.

Retrieving posts associated to a topic #api-topic-posts

GET /api/1.0/topics/{api-topic.id}/posts/

Use this endpoint to retrieve a list of posts associated to the specific topic. By default this API will returns all posts. For a more specific query scope, please see #api-topic-posts-scoped.

Query string Description
?topic=1 Include the topic in a topic object.
?board=1 Include the board in a boards object. Only if topic is present.

Response

Field Type Description
type String

The type of API object. The value is always "post".

"type":"post"
id Integer

Internal ID for the post.

"id":1
body String

The post body entered by the user in new topic or reply form.

"body":"..."
body_formatted String

Same as body but format it to HTML using internal formatter.

"body_formatted":"<p>...</p>"
bumped Boolean

A flag whether the post bumped the topic to top of the board.

"bumped":true
created_at String

ISO 8601-formatted datetime of when the post was created.

"created_at":"2013-02-06T16:45:20.275693-08:00"
ident String

Unique ID for each user that was generated when the board has use_ident enabled.

"ident":"7xFKuAP5G"
ident_type String

The type of the user ident to distinguish user info.

  • ident — normal user ident
  • ident_admin — admin ident
"ident_type":"ident"
name String

The name entered for this post.

"name":"Nameless Fanboi"
number Integer

Order of the post within the topic.

"number":1
topic_id Integer

Internal ID of a topic the post is associated with.

"topic_id":1
path String

The path to this resource.

"path":"/api/1.0/topics/1/posts/"

Retrieving posts associated to a topic with scope #api-topic-posts-scoped

GET /api/1.0/topics/{api-topic.id}/posts/{query}/

Use this endpoint to scope posts with the given queries. The query could be one of the following:

Query Description
{n} Query a single post with n number.
{n1}-{n2} Query posts from n1 to n2. If n1 or n2 is not given, 0 and last post are assumed respectively.
l{n} Query the last n posts, for example, l10 will list the last 10 posts.
recent Alias for l30.
Query string Description
?topic=1 Include the topic in a topic object.
?board=1 Include the board in a boards object. Only if topic is present.

Response

Same as #api-topic-posts.

Retrieving pages #api-pages

GET /api/1.0/pages/

Use this endpoint to retrieve a list of all pages. Usually these pages will contain static content, such as guidelines or help.

Response

Array containing #api-page.

Retrieving a page #api-page

GET /api/1.0/pages/{api-page.slug}/

Use this endpoint to retrieve any individual page.

Response

Field Type Description
type String

The type of API object. The value is always "page".

"type":"page"
id Integer

Internal ID for the page.

"id":1
body String

The page body.

"body":"..."
body_formatted String

Same as body but format it using specified formatter. Note that this field is meant to be rendered in a HTML viewer and will escape the body in case the formatter is "none". If the content will not be displayed in a HTML viewer in case the formatter is "none", body must be used instead.

"body_formatted":"<p><em>Hello, world</em></p>\n"
formatter String

Name of a formatter to format this page's body. Available values are:

  • markdown — render this page using Markdown formatter (see also Misaka).
  • html — render this page as HTML without any escaping.
  • none — render this page as text or escape HTML as appropriate.
"formatter":"markdown"
namespace String

Namespace of this page, usually "public".

"namespace":"public"
slug String

The identity of this page.

"slug":"hello"
title String

The title of this page.

"title":"Hello, world!"
updated_at String

ISO 8601-formatted datetime of when the post was updated.

"updated_at":"2016-10-29T14:59:12.451212-08:00"
path String

The path to this resource.

"page":"/api/1.0/pages/hello/"

Retrieving a specific task #api-task

GET /api/1.0/tasks/{task.id}/

Use this endpoint to retrieve a status of a task.

Response

Field Type Description
type String

The type of API object. The value is always "task".

"type":"task"
id String

Internal ID for the task.

"id":"aff5dede-7f4e-4e48-ad4d-2f6396a5e75c"
status String

Status string of the task. Available values are:

  • queued — the task has been successfully queued.
  • pending — the task is waiting to be processed.
  • started — the task has started processing.
  • retry — the task processing has failed due to internal errors and is queued for a retry.
  • failure — the task has failed due to internal errors and could not be retried.
  • success — the task has been processed successfully.

Normally it is safe to ignore all statuses except for success. Note that success only refer to the status of the task processing and not the result. For example, it is normal for task to report success status for a post that is rejected by a spam filter. In all cases, always refer to data for the result.

"status":"open"
data Object

Result of task processing. It could be one of the following objects depending on the type of task.

Only available if status is success.

"data":{ ... }
path String

The path to this resource.

"path":"/api/1.0/tasks/aff5dede-7f4e-4e48-ad4d-2f6396a5e75c/"

Errors #api-error

An object representing general errors.

Object

Field Type Description
type String

The type of API object. The value is always "error".

"type":"error"
status String

Error status. Available statuses are:

  • unknown — an unknown error occurred.
  • rate_limited — this IP address has been rate-limited.
  • params_invalid — required parameters are missing from the request.

In case of post rejection, the following statuses are returned:

  • akismet_rejected — the post or topic has been identified as spam by Akismet.
  • dnsbl_rejected — the IP address is listed in one of DNSBL databases.
  • ban_rejected — the IP address is listed in the ban list.
  • proxy_rejected — the IP address has been identified as an open proxy or public VPN.
  • status_rejected — this board or topic disallows posting.
"status":"rate_limited"
message String

Description of the error.

"message":"Please wait 20 seconds before retrying."