Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/artemis-development-group/artemis/llms.txt

Use this file to discover all available pages before exploring further.

Posts (internally called Links) are the primary content unit in Artemis. Each post belongs to a branch and is either a link submission pointing to an external URL or a self-post containing inline text. The Posts API covers submission, sorted listings, voting, saving, reporting, and deletion. All write operations require an authenticated session or a valid OAuth2 bearer token.

​
POST /api/submit

Submits a new post to a branch. Requires the submit OAuth2 scope.
​
title
string
required
The post title. Maximum length is enforced by the server.
​
sr
string
required
The name of the branch to submit to (e.g. programming).
​
kind
string
required
Post type. Use link for a URL submission or self for a text post.
​
url
string
The URL to submit. Required when kind is link.
​
text
string
The body text of the self-post in Markdown. Used when kind is self.
​
resubmit
boolean
default:"false"
When true, allows submitting a URL that has already been posted to the branch without returning an ALREADY_SUB error.
​
sendreplies
boolean
default:"true"
When true, comment reply notifications are sent to the post author’s inbox. Defaults to true for self-posts.
​
nsfw
boolean
default:"false"
Mark the post as NSFW.
​
spoiler
boolean
default:"false"
Mark the post as a spoiler.
​
extension
string
Extension used for the redirect URL if a resubmit error occurs (e.g. json).
curl -X POST https://<your-artemis-instance>/api/submit \
  -H "Authorization: Bearer <token>" \
  -d "title=An+interesting+article&sr=programming&kind=link&url=https://example.com/article"

{
  "json": {
    "errors": [],
    "data": {
      "url": "/r/programming/comments/abc12/an_interesting_article/",
      "id": "abc12",
      "name": "t3_abc12"
    }
  }
}
​
url
string
The permalink to the newly created post.
​
id
string
The base-36 ID of the new post.
​
name
string
The fullname of the new post (type prefix t3_ followed by the base-36 ID).
Submission is rate-limited per user and per IP. Exceeding the rate limit returns an error with code RATELIMIT.

​
GET /r/:branch/:sort.json

Returns a paginated listing of posts in a branch, sorted as specified. No authentication is required for public branches.
​
branch
string
required
The branch name.
​
sort
string
required
Sort method. One of hot, new, top, rising, or controversial.
​
t
string
default:"day"
Time window used when sort is top or controversial. One of hour, day, week, month, year, or all.
​
after
string
Fullname cursor for forward pagination.
​
before
string
Fullname cursor for backward pagination.
​
limit
number
default:"25"
Number of posts to return. Maximum is 100.
curl "https://<your-artemis-instance>/r/programming/hot.json?limit=10"

{
  "kind": "Listing",
  "data": {
    "after": "t3_xyz99",
    "before": null,
    "children": [
      {
        "kind": "t3",
        "data": {
          "id": "abc12",
          "name": "t3_abc12",
          "title": "An interesting article",
          "author": "alice",
          "subreddit": "programming",
          "score": 482,
          "url": "https://example.com/article",
          "is_self": false,
          "selftext": "",
          "num_comments": 34,
          "over_18": false,
          "created_utc": 1714000000,
          "permalink": "/r/programming/comments/abc12/an_interesting_article/"
        }
      }
    ]
  }
}
​
id
string
Base-36 post ID.
​
name
string
Fullname (e.g. t3_abc12).
​
title
string
Post title.
​
author
string
Username of the post author.
​
subreddit
string
Branch the post was submitted to.
​
score
number
Net vote score (upvotes minus downvotes).
​
url
string
The URL of a link post, or the post’s own permalink for self-posts.
​
is_self
boolean
Whether the post is a self-post.
​
selftext
string
Body text for self-posts in Markdown. Empty for link posts.
​
num_comments
number
Total comment count.
​
over_18
boolean
Whether the post is marked NSFW.
​
created_utc
number
Unix timestamp of post creation.
​
permalink
string
Relative URL to the post’s comment page.

​
GET /comments/:article.json

Returns a post together with its full comment tree. The first element of the response array is the post listing; the second is the comment listing.
​
article
string
required
The base-36 ID of the post.
​
sort
string
default:"confidence"
Comment sort order. One of confidence, top, new, controversial, old, random, or qa.
​
limit
number
default:"200"
Maximum number of comments to return.
​
depth
number
Maximum depth of comment subtrees to include.
​
context
number
Number of parent comments to show when a specific comment ID is supplied.
​
comment
string
Base-36 ID of a specific comment to focus the response on.
curl "https://<your-artemis-instance>/comments/abc12.json?sort=top&limit=50"
The response is a two-element JSON array: [post_listing, comment_listing].

​
POST /api/vote

Casts a vote on a post or comment. Requires the vote OAuth2 scope. See also Comments — voting.
​
id
string
required
The fullname of the post or comment to vote on (e.g. t3_abc12).
​
dir
number
required
Vote direction. 1 for an upvote, -1 for a downvote, 0 to retract a previous vote.
​
rank
number
The rank of the item in the listing at the time of voting, for analytics purposes.
curl -X POST https://<your-artemis-instance>/api/vote \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12&dir=1"
Votes must represent genuine human actions. Automated bots that cast votes independently, or that amplify votes beyond a one-to-one reflection of a human action, violate the platform rules.

​
Saving and unsaving posts

Saves a post or comment to the authenticated user’s saved list. Requires the save scope.
​
id
string
required
Fullname of the post or comment to save (e.g. t3_abc12).
​
category
string
Optional save category name. Available only to gold accounts.
curl -X POST https://<your-artemis-instance>/api/save \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12"

​
POST /api/report

Reports a post (or comment) to the branch’s moderators. Reporting a post also hides it from the reporting user’s listing view unless they are an admin or moderator.
​
id
string
required
Fullname of the post or comment to report.
​
reason
string
A short reason string. Pass site_reason_selected to use a site-level reason, or other to supply a custom message via other_reason.
​
site_reason
string
The selected site-level reason (used when reason is site_reason_selected).
​
other_reason
string
Custom reason text. Maximum 100 characters. Used when reason is other.
curl -X POST https://<your-artemis-instance>/api/report \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12&reason=spam"

​
GET /api/info.json

Returns a listing of posts matching a URL or a set of fullnames.
​
url
string
A URL to look up posts for. When provided, returns posts that link to this URL.
​
id
string
Comma-separated list of up to 100 fullnames to look up (e.g. t3_abc12,t3_def34).
# Look up by URL
curl "https://<your-artemis-instance>/api/info.json?url=https://example.com/article"

# Look up by fullname
curl "https://<your-artemis-instance>/api/info.json?id=t3_abc12"

​
POST /api/del

Deletes a post. Only the post’s author can delete it. Requires the edit OAuth2 scope.
​
id
string
required
Fullname of the post to delete (e.g. t3_abc12).
curl -X POST https://<your-artemis-instance>/api/del \
  -H "Authorization: Bearer <token>" \
  -d "id=t3_abc12"
Deleting a post removes it from all branch listings and is not reversible through the API. The post’s comment thread will still be accessible but the post body will appear as [deleted].

Build docs developers (and LLMs) love

Get started for freeTalk to us