API docs by Redocly

Artalk API (2.0)

Download OpenAPI specification:

API Support: artalkjs@gmail.com URL: https://artalk.js.org License: MIT

Artalk is a modern comment system based on Golang.

Auth

Login by email

Login by email with verify code (Need send email verify code first) or password

Request Body schema: application/json
required

The data to login

code
string
email
required
string
password
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "email": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Register by email

Register by email and verify code (if user exists, will update user, like forget or change password. Need send email verify code first)

Request Body schema: application/json
required

The data to register

code
required
string
email
required
string
link
string
name
string
password
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "email": "string",
  • "link": "string",
  • "name": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Send verify email

Send email including verify code to user

Request Body schema: application/json
required

The data

email
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "string"
}

Response samples

Content type
application/json
{
  • "msg": "string"
}

Check data merge

Get all users with same email, if there are more than one user with same email, need merge

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "need_merge": true,
  • "user_names": [
    ]
}

Apply data merge

This function is to solve the problem of multiple users with the same email address, should be called after user login and then check, and perform data merge.

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The data

user_name
required
string

Responses

Request samples

Content type
application/json
{
  • "user_name": "string"
}

Response samples

Content type
application/json
{
  • "deleted_user_count": 0,
  • "update_comments_count": 0,
  • "update_notifies_count": 0,
  • "update_votes_count": 0,
  • "user_token": "string"
}

Exchange an external IdP access token for an Artalk JWT

Validates a third-party OIDC access token by calling the issuer's /userinfo endpoint, requires a verified email claim, then mints an Artalk session JWT. Use when the surrounding application already runs OIDC and you want Artalk comments to inherit that session without showing Artalk's own login UI.

Request Body schema: application/json
required

External SSO token

token
required
string

External IdP access token (e.g. an Auth0 access token)

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Get User Info

Get user info to prepare for login or check current user status

Authorizations:
ApiKeyAuth
query Parameters
email
string

The user email

name
string

The username

Responses

Response samples

Content type
application/json
{
  • "is_login": true,
  • "notifies": [
    ],
  • "notifies_count": 0,
  • "user": {
    }
}

Update user profile

Update user profile when user is logged in

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The profile data to update

code
string
email
required
string
link
string
name
required
string

Responses

Request samples

Content type
application/json
{
  • "code": "string",
  • "email": "string",
  • "link": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "user": {
    }
}

Get Access Token

Login user by name or email

Request Body schema: application/json
required

The user login data

email
required
string

The user email

name
string

The username

password
required
string

The user password

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string",
  • "password": "string"
}

Response samples

Content type
application/json
{
  • "token": "string",
  • "user": {
    }
}

Get Login Status

Get user login status by header Authorization

Authorizations:
ApiKeyAuth
query Parameters
email
string

The user email

name
string

The username

Responses

Response samples

Content type
application/json
{
  • "is_admin": true,
  • "is_login": true
}

Cache

Flush Cache

Flush all cache on the server

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "msg": "string"
}

Warm-Up Cache

Cache warming helps you to pre-load the cache to improve the performance of the first request

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "msg": "string"
}

Captcha

Get Captcha

Get a base64 encoded captcha image or a HTML page to verify for user

Responses

Response samples

Content type
application/json
{
  • "img_data": "string"
}

Get Captcha Status

Get the status of the user's captcha verification

Responses

Response samples

Content type
application/json
{
  • "is_pass": true
}

Verify Captcha

Verify user enters correct captcha code

Request Body schema: application/json
required

The data to check

value
required
string

The captcha value to check

Responses

Request samples

Content type
application/json
{
  • "value": "string"
}

Response samples

Content type
application/json
{ }

Comment

Get Comment List

Get a list of comments by some conditions

Authorizations:
ApiKeyAuth
query Parameters
email
string

The user email

flat_mode
boolean

Enable flat_mode

limit
integer

The limit for pagination

name
string

The username

offset
integer

The offset for pagination

page_key
required
string

The comment page_key

scope
string
Enum: "page" "user" "site"

The scope of comments

search
string

Search keywords

site_name
string

The site name of your content scope

sort_by
string
Enum: "date_asc" "date_desc" "vote"

Sort by condition

type
string
Enum: "all" "mentions" "mine" "pending"

Message center show type

view_only_admin
boolean

Only show comments by admin

Responses

Response samples

Content type
application/json
{
  • "comments": [
    ],
  • "count": 0,
  • "page": {
    },
  • "roots_count": 0
}

Create Comment

Create a new comment

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The comment data

content
required
string

The comment content

email
required
string

The comment email

link
string

The comment link

name
required
string

The comment name

page_key
required
string

The comment page_key

page_title
string

The comment page_title

rid
integer

The comment rid

site_name
required
string

The site name of your content scope

ua
string

The comment ua

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "email": "string",
  • "link": "string",
  • "name": "string",
  • "page_key": "string",
  • "page_title": "string",
  • "rid": 0,
  • "site_name": "string",
  • "ua": "string"
}

Response samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "content": "string",
  • "content_marked": "string",
  • "date": "string",
  • "email_encrypted": "string",
  • "id": 0,
  • "ip_region": "string",
  • "is_allow_reply": true,
  • "is_collapsed": true,
  • "is_pending": true,
  • "is_pinned": true,
  • "is_verified": true,
  • "link": "string",
  • "nick": "string",
  • "page_key": "string",
  • "page_url": "string",
  • "rid": 0,
  • "site_name": "string",
  • "ua": "string",
  • "user_id": 0,
  • "visible": true,
  • "vote_down": 0,
  • "vote_up": 0
}

Get a comment

Get the detail of a comment by comment id

path Parameters
id
required
integer

The comment ID you want to get

Responses

Response samples

Content type
application/json
{
  • "comment": {
    },
  • "reply_comment": {
    }
}

Update Comment

Update a specific comment

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The comment ID you want to update

Request Body schema: application/json
required

The comment data

content
required
string

The comment content

email
string

The comment email

ip
string

The comment ip

is_collapsed
required
boolean

The comment is_collapsed

is_pending
required
boolean

The comment is_pending

is_pinned
required
boolean

The comment is_pinned

link
string

The comment link

nick
string

The comment nick

page_key
required
string

The comment page_key

rid
required
integer

The comment rid

site_name
required
string

The site name of your content scope

ua
string

The comment ua

Responses

Request samples

Content type
application/json
{
  • "content": "string",
  • "email": "string",
  • "ip": "string",
  • "is_collapsed": true,
  • "is_pending": true,
  • "is_pinned": true,
  • "link": "string",
  • "nick": "string",
  • "page_key": "string",
  • "rid": 0,
  • "site_name": "string",
  • "ua": "string"
}

Response samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "content": "string",
  • "content_marked": "string",
  • "date": "string",
  • "email_encrypted": "string",
  • "id": 0,
  • "ip_region": "string",
  • "is_allow_reply": true,
  • "is_collapsed": true,
  • "is_pending": true,
  • "is_pinned": true,
  • "is_verified": true,
  • "link": "string",
  • "nick": "string",
  • "page_key": "string",
  • "page_url": "string",
  • "rid": 0,
  • "site_name": "string",
  • "ua": "string",
  • "user_id": 0,
  • "visible": true,
  • "vote_down": 0,
  • "vote_up": 0
}

Delete Comment

Delete a specific comment

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The comment ID you want to delete

Responses

Response samples

Content type
application/json
{ }

System

Get System Configs

Get System Configs for UI

Responses

Response samples

Content type
application/json
{
  • "frontend_conf": { },
  • "version": {
    }
}

Get Social Login Providers

Get social login providers

Responses

Response samples

Content type
application/json
{
  • "anonymous": true,
  • "providers": [
    ]
}

Get Domain Info

Get Domain Info

query Parameters
url
string

Domain URL

Responses

Response samples

Content type
application/json
{
  • "is_trusted": true,
  • "origin": "string"
}

Send Email

Send an email to test the email sender

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The email data

body
required
string

The body of email

subject
required
string

The subject of email

to_addr
required
string

The email address of the receiver

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "subject": "string",
  • "to_addr": "string"
}

Response samples

Content type
application/json
{ }

Get Settings

Get settings from app config file

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "envs": [
    ],
  • "yaml": "string"
}

Save and apply Settings

Apply settings and restart the server

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The settings

yaml
required
string

The content of the config file in YAML format

Responses

Request samples

Content type
application/json
{
  • "yaml": "string"
}

Response samples

Content type
application/json
{ }

Get Settings Template

Get config templates in different languages for rendering the settings page in the frontend

Authorizations:
ApiKeyAuth
path Parameters
locale
required
string

The locale of the settings template you want to get

Responses

Response samples

Content type
application/json
{
  • "yaml": "string"
}

Get Version Info

Get the version of Artalk

Responses

Response samples

Content type
application/json
{
  • "app": "string",
  • "commit_hash": "string",
  • "version": "string"
}

Notify

Get Notifies

Get a list of notifies for user

query Parameters
name
required
string

The user name

email
required
string

The user email

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "notifies": [
    ]
}

Mark All Notifies as Read

Mark all notifies as read for user

Request Body schema: application/json
required

The options

email
required
string

The user email

name
required
string

The username

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{ }

Mark Notify as Read

Mark specific notification as read for user

path Parameters
comment_id
required
integer

The comment id of the notify you want to mark as read

notify_key
required
string

The key of the notify

Responses

Response samples

Content type
application/json
{ }

Page

Get Page List

Get a list of pages by some conditions

Authorizations:
ApiKeyAuth
query Parameters
limit
integer

The limit for pagination

offset
integer

The offset for pagination

search
string

Search keywords

site_name
string

The site name of your content scope

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "pages": [
    ]
}

Fetch All Pages Data

Fetch the data of all pages

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The options

site_name
string

If not empty, only fetch pages of this site

Responses

Request samples

Content type
application/json
{
  • "site_name": "string"
}

Response samples

Content type
application/json
{ }

Get Pages Fetch Status

Get the status of the task of fetching all pages

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "done": 0,
  • "is_progress": true,
  • "msg": "string",
  • "total": 0
}

Increase Page Views (PV)

Increase and get the number of page views

Request Body schema: application/json
required

The page to record pv

page_key
required
string

The page key

page_title
string

The page title

site_name
string

The site name of your content scope

Responses

Request samples

Content type
application/json
{
  • "page_key": "string",
  • "page_title": "string",
  • "site_name": "string"
}

Response samples

Content type
application/json
{
  • "pv": 0
}

Update Page

Update a specific page

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The page ID you want to update

Request Body schema: application/json
required

The page data

admin_only
required
boolean

Updated page admin_only option

key
required
string

Updated page key

site_name
required
string

The site name of your content scope

title
required
string

Updated page title

Responses

Request samples

Content type
application/json
{
  • "admin_only": true,
  • "key": "string",
  • "site_name": "string",
  • "title": "string"
}

Response samples

Content type
application/json
{
  • "admin_only": true,
  • "date": "string",
  • "id": 0,
  • "key": "string",
  • "pv": 0,
  • "site_name": "string",
  • "title": "string",
  • "url": "string",
  • "vote_down": 0,
  • "vote_up": 0
}

Delete Page

Delete a specific page

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The page ID you want to delete

Responses

Response samples

Content type
application/json
{ }

Fetch Page Data

Fetch the data of a specific page

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The page ID you want to fetch

Responses

Response samples

Content type
application/json
{
  • "admin_only": true,
  • "date": "string",
  • "id": 0,
  • "key": "string",
  • "pv": 0,
  • "site_name": "string",
  • "title": "string",
  • "url": "string",
  • "vote_down": 0,
  • "vote_up": 0
}

Site

Get Site List

Get a list of sites by some conditions

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "sites": [
    ]
}

Create Site

Create a new site

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The site data

name
required
string

The site name

urls
required
Array of strings

The site urls

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "urls": [
    ]
}

Response samples

Content type
application/json
{
  • "first_url": "string",
  • "id": 0,
  • "name": "string",
  • "urls": [
    ],
  • "urls_raw": "string"
}

Update Site

Update a specific site

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The site ID you want to update

Request Body schema: application/json
required

The site data

name
required
string

Updated site name

urls
required
Array of strings

Updated site urls

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "urls": [
    ]
}

Response samples

Content type
application/json
{
  • "first_url": "string",
  • "id": 0,
  • "name": "string",
  • "urls": [
    ],
  • "urls_raw": "string"
}

Site Delete

Delete a specific site

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The site ID you want to delete

Responses

Response samples

Content type
application/json
{ }

Statistic

Statistic

Get the statistics of various data analysis

path Parameters
type
required
string
Enum: "latest_comments" "latest_pages" "pv_most_pages" "comment_most_pages" "page_pv" "site_pv" "page_comment" "site_comment" "rand_comments" "rand_pages"

The type of statistics

query Parameters
limit
integer

The limit for pagination

page_keys
string

multiple page keys separated by commas

site_name
string

The site name of your content scope

Responses

Response samples

Content type
application/json
{
  • "data": null,
  • "msg": "string"
}

Transfer

Export Artrans

Export data from Artalk

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "artrans": "string"
}

Import Artrans

Import data to Artalk

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The data to import

assumeyes
boolean

Automatically answer yes for all questions

json_data
string

The JSON data

json_file
string

The JSON file path

target_site_name
string

The target site name

target_site_url
string

The target site url

url_keep_domain
boolean

Keep domain

url_resolver
boolean

Enable URL resolver

Responses

Request samples

Content type
application/json
{
  • "assumeyes": true,
  • "json_data": "string",
  • "json_file": "string",
  • "target_site_name": "string",
  • "target_site_url": "string",
  • "url_keep_domain": true,
  • "url_resolver": true
}

Upload Artrans

Upload a file to prepare to import

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Upload file in preparation for import task

Responses

Response samples

Content type
application/json
{
  • "filename": "string"
}

Upload

Upload

Upload file from this endpoint

Authorizations:
ApiKeyAuth
Request Body schema: multipart/form-data
required
file
required
string <binary>

Upload file

Responses

Response samples

Content type
application/json
{
  • "file_name": "string",
  • "file_type": "string",
  • "public_url": "string"
}

User

Create User

Create a new user

Authorizations:
ApiKeyAuth
Request Body schema: application/json
required

The user data

badge_color
string

The user badge color (hex format)

badge_name
string

The user badge name

email
required
string

The user email

is_admin
required
boolean

The user is an admin

link
string

The user link

name
required
string

The user name

password
string

The user password

receive_email
required
boolean

The user receive email

Responses

Request samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "email": "string",
  • "is_admin": true,
  • "link": "string",
  • "name": "string",
  • "password": "string",
  • "receive_email": true
}

Response samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "comment_count": 0,
  • "email": "string",
  • "id": 0,
  • "is_admin": true,
  • "is_in_conf": true,
  • "last_ip": "string",
  • "last_ua": "string",
  • "link": "string",
  • "name": "string",
  • "receive_email": true
}

Update User

Update a specific user

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The user ID you want to update

Request Body schema: application/json
required

The user data

badge_color
string

The user badge color (hex format)

badge_name
string

The user badge name

email
required
string

The user email

is_admin
required
boolean

The user is an admin

link
string

The user link

name
required
string

The user name

password
string

The user password

receive_email
required
boolean

The user receive email

Responses

Request samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "email": "string",
  • "is_admin": true,
  • "link": "string",
  • "name": "string",
  • "password": "string",
  • "receive_email": true
}

Response samples

Content type
application/json
{
  • "badge_color": "string",
  • "badge_name": "string",
  • "comment_count": 0,
  • "email": "string",
  • "id": 0,
  • "is_admin": true,
  • "is_in_conf": true,
  • "last_ip": "string",
  • "last_ua": "string",
  • "link": "string",
  • "name": "string",
  • "receive_email": true
}

Delete User

Delete a specific user

Authorizations:
ApiKeyAuth
path Parameters
id
required
integer

The user ID you want to delete

Responses

Response samples

Content type
application/json
{ }

Get User List

Get a list of users by some conditions

Authorizations:
ApiKeyAuth
path Parameters
type
required
string
Enum: "all" "admin" "in_conf"

The type of users

query Parameters
limit
integer

The limit for pagination

offset
integer

The offset for pagination

search
string

Search keywords

Responses

Response samples

Content type
application/json
{
  • "count": 0,
  • "users": [
    ]
}

Vote

Sync Vote Data

Sync the number of votes in the comments or pages data tables to keep them the same as the votes table

Authorizations:
ApiKeyAuth

Responses

Response samples

Content type
application/json
{ }

Get Vote Status

Get vote status for a specific comment or page

path Parameters
target_name
required
string
Enum: "comment" "page"

The name of vote target

target_id
required
integer

The target comment or page ID

Responses

Response samples

Content type
application/json
{
  • "down": 0,
  • "is_down": true,
  • "is_up": true,
  • "up": 0
}

Create Vote

Create a new vote for a specific comment or page

path Parameters
target_name
required
string
Enum: "comment" "page"

The name of vote target

target_id
required
integer

The target comment or page ID

choice
required
string
Enum: "up" "down"

The vote choice

Request Body schema: application/json
required

The vote data

email
string

The user email

name
string

The username

Responses

Request samples

Content type
application/json
{
  • "email": "string",
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "down": 0,
  • "is_down": true,
  • "is_up": true,
  • "up": 0
}