Page MenuHomePhuks

API v3 documentation
Updated 210 Days AgoPublic

Version 5 of 5: You are viewing the current published version of this document.

The v3 API is on https://phuks.co/api/v3/, it will always return JSON.

Response codes

    • 200: Request successful
    • 401: access_token expired: Upon encountering this error the client must refresh its access token and retry the request
    • 422: Invalid token
    • 423: Challenge required. Upon encountering this error the client must request a challenge and retry the request, sending challenge_token and challenge_response POST parameters. If a challenge response has been sent but the response is invalid, a boolean failed parameter will be set to true
  • 429: Rate limited. Wait at least 30 seconds and retry request.
    • Any other 4xx code is obviously an error. A human-readable error message is always sent on msg

Tokens

The user is identified by a short-lived access_token and a long-lived refresh_token. Both are returned by the login method. When the access_token expires, a new one can be requested via the refresh method, where the refresh_token is used instead of the access_token.

Certain actions can only be performed with a fresh access_token. Fresh access tokens are those returned by the login or fresh-login methods (the access_token returned by the refresh method is not fresh).

The token must be sent to the API via a Bearer Authorization header.

Example: Authorization: Bearer <your.token.here>

Methods

[POST] /login

Returns a fresh access_token and a refresh_token used to perform actions on behalf of a user.

Parameters:

  • username
  • password
  • client: Text identifying the client (treat as an user agent string)

Returns:

  • access_token
  • refresh_token

[POST] /refresh

Returns a new access_token. A refresh_token must be passed in the Authorization header.

Parameters: none.

Returns:

  • access_token

[POST] /fresh-login

Identical to login but does not return a new refresh_token

Parameters:

  • username
  • password

Returns:

  • access_token

[GET] /getPost/<pid>

Returns all information about a post. pid is the numerical post identifier.

Returns:

  • comments: Comment count
  • content: Markdown parsed* post content
  • deleted (bool): whether the post has been deleted
  • downvotes: Number of downvotes the post has received
  • edited: Timestamp of the last time the post was edited or null if it was not.
  • flair: The post's flair. Null if there is no flair
  • link: The post's link. Null if it is a text post or a poll
  • **nsfw* (bool): whether the post has been tagged as NSFW
  • pid: the post's unique identifier
  • posted: Timestamp of the post's creation
  • ptype: Post type: 0 for text posts, 1 for link posts and 3 for polls.
  • score: upvotes - downvotes
  • sub: The name of the sub where the post belongs
  • thumbnail: filename of the post's thumbnail or empty string if the post has no thumbnail
  • title: The post's title
  • uid: Unique identifier for the user that created the post
  • upvotes: The number of upvotes the post has received
  • user: Name of the user that created the post

[GET] /getPost/<pid>/comments[/<cid>[/<lim>]]

Returns a comments array with all the post's comments, paginated.

Parameters:

  • pid: the unique identifier of a post.
  • cid (optional): If supplied, only the children comments of cid (unique identifier for a comment) will be loaded
  • lim (optional): If supplied together with cid, only comments after this key will be returned

Returns:

  • children: An array with all the children of the current comment
  • cid: An unique identifier for the comment
  • content: the content of the comment, markdown parsed*
  • downvotes: Number of downvotes the comment has received
  • lastedit: Timestamp of the last time the comment was edited or null if it was not.
  • pid: The identifier of the post this comment belongs to
  • score: upvotes - downvotes
  • status: null if the comment was not deleted
  • time: Timestamp of the comment's creation
  • uid: Unique identifier for the user that created the post
  • upvotes: The number of upvotes the post has received
  • user: Name of the user that created the post
Pagination

If a comment with a key and more fields is reached, to load more comments the key parameter must be passed as lim to this method together with the parent comment's cid, even if that comment has no parent (in which case the string "null" or "0" must be passed to the cid parameter)

If a comment with a more field but no key field is reached, to load more comments the parent's cid must be passed as the cid parameter to this method.

[GET] /getPostList/<target>/<sort>[/<page>]

Returns a list of posts.

Parameters:

  • target: Either all, home or the name of a sub.
  • sort: Either hot, top, new or default. default is only allowed if target is a sub.
  • page

Returns:

  • A list of posts, identical in format to the getPost method

[POST] /vote/post/<pid>/<value>

Issues a vote to a post.

Parameters:

  • pid
  • value: either up to issue an upvote or down to issue a downvote.

Response:

  • score: The updated post's score
  • rm (bool): Whether a previously issued vote has been removed*

[POST] /vote/comment/<cid>/<value>

Identical to /vote/post, but requiring a cid instead of a pid.

[POST] /create/comment

Creates a comment.

Parameters:

  • pid
  • parentcid (optional): The cid of the parent comment. If not provided a root comment is created
  • content

Returns:

  • pid
  • cid

[POST] /create/post

Creates a post.

Parameters:

  • ptype
  • sub
  • title
  • link (only required if ptype is 1)
  • content (optional)
  • nsfw (bool, optional)

Returns:

  • pid
  • sub

[GET] /challenge

Used to request a challenge and gain access to methods that require one.

Returns:

  • challenge_token: unique token that must be returned to the method that requested the challente
  • challenge_blob: base64 encoded PNG image of the challenge

[GET] /search/sub

Performs a sub search by name. (Used for auto-completion).

Parameters:

  • query (at least three characters long)

Returns:

  • results: an array of subs whose name matched the query

[POST] /edit/comment

Edits a comment. Does not return anything on success.

Parameters:

  • cid
  • content
Last Author
Polsaker
Last Edited
Apr 21 2019, 2:52 AM

Event Timeline

Polsaker created this document.Apr 20 2019, 5:22 AM
Polsaker edited the content of this document. (Show Details)
Polsaker added a project: Development.
Polsaker edited the content of this document. (Show Details)Apr 20 2019, 3:20 PM
Polsaker edited the content of this document. (Show Details)Apr 21 2019, 1:06 AM
Polsaker published a new version of this document.
Polsaker edited the content of this document. (Show Details)
Polsaker edited the content of this document. (Show Details)Apr 21 2019, 2:52 AM