Help: API

[Back: e621:index]

e621 offers a simple API to make scripting easy. All you need is a way to GET and POST to URLs. The ability to parse XML or JSON responses is nice, but not critical. The simplicity of the API means you can write scripts using JavaScript, Perl, Python, Ruby, even shell languages like bash or tcsh.

Basics | Posts | Tags | Aliases | Implications | Artists | Comments | Blips | Wiki | Notes | Users | User Records | Dmail | Forum | Pools | Sets | Favorites | Tag History | Flag History | Tickets

Basics

[ Return to top ↑ ]

HTTP defines two request methods: GET and POST. You'll be using these two methods to interact with the e621 API. Most API calls that change the state of the database (like creating, updating, or deleting something) require an HTTP POST call. API calls that only retrieve data can typically be done with an HTTP GET call.

In the e621 API, a URL is analogous to a function name. You pass in the function parameters as a query string. Here's an extremely simple example:

/post/index.xml?limit=1

The post part indicates the controller we're working with. In this case it's posts. index describes the action. Here we're retrieving a list of posts. Finally, the xml part describes what format we want the response in. You can specify .xml for XML responses, .json for JSON responses, and nothing at all for HTML responses.

We also offer JSONP support. Just append callback=myfunction to your query string and the resulting JSON will be encapsulated within a call to myfunction. For example, /blip/index.json?callback=myfunction would return something like:

myfunction([{"user":"A User","response":null,"body":"Blip one","user_id":1,"id":1}])

NOTICE: If you are using cURL or another similar HTTP library and API calls seem to fail for no reason, it may be a problem with SSL. If this is the case, you will need to point cURL to a trusted certificate to compare the remote site's (e621.net) certificate with. For example, Mozilla's certificate bundle is a good one to use. Get it here and save it somewhere in your server directory. Then point cURL to the file with something like this:

curl_setopt($ch, CURLOPT_CAINFO, "/server_dir/apache/cacert.pem");

You can also simply disable SSL verification altogether, although this eliminates the advantage of using SSL in the first place:

curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);

NOTICE #2: A non-empty User-Agent header is required for all requests. Please pick a unique User-Agent for your project. You are encouraged to include your e621 username so that you may be contacted if your project causes problems. DO NOT impersonate a browser user agent, as this will get you blocked. An example user-agent would be

MyProject/1.0 (by username on e621)

Responses

All API calls that change state will return a single element response (for XML calls). They are formatted like this:

<?xml version="1.0" encoding="UTF-8"?>
<response success="false" reason="duplicate"/>

For JSON responses, they'll look like this:

{success: false, reason: "duplicate"}

While you can usually determine success or failure based on the response object, you can also figure out what happened based on the HTTP status code. In addition to the standard ones, e621 uses some custom status codes in the 4xx and 5xx range.

Status CodeMeaning
200 OKRequest was successful
403 ForbiddenAccess denied. May indicate that your request lacks a User-Agent header (see Notice #2 above).
404 Not FoundNot found
420 Invalid RecordRecord could not be saved
421 User ThrottledUser is throttled, try again later
422 LockedThe resource is locked and cannot be modified
423 Already ExistsResource already exists
424 Invalid ParametersThe given parameters were invalid
500 Internal Server ErrorSome unknown error occurred on the server
502 Bad GatewayA gateway server received an invalid response from the e621 servers
503 Service UnavailableServer cannot currently handle the request or you have exceeded the request rate limit. Try again later or decrease your rate of requests.
520 Unknown ErrorUnexpected server response which violates protocol
522 Origin Connection Time-outCloudFlare's attempt to connect to the e621 servers timed out
524 Origin Connection Time-outA connection was established between CloudFlare and the e621 servers, but it timed out before an HTTP response was received
525 SSL Handshake FailedThe SSL handshake between CloudFlare and the e621 servers failed

JSON Responses

While you will probably want to work with XML in the majority of cases, if you're writing something in Javascript then the JSON responses may be preferable. They are much faster to parse and there's less code to write to get your data structure:

var data = JSON.parse(responseText)
alert(data.response)

Logging In

Some actions may require you to log in. For any action you can always specify two parameters to identify yourself:

  • login Your username
  • password_hash Your API key. For legacy reasons this field does not reflect what it actually contains.

The API now requires that API access be enabled on the account before it can log in using the API. To enable API access, you must go to your account settings and generate an API key. Then, and only then will the below method of logging in work. If you do not have an API key generated, you will receive a failed login, even if the details are correct.

If you have a previously obtained password_hash value from before the switch to API keys, it is no longer valid and must be replaced with an API key.

You may obtain your API key from the API key page, or through the following call:

e621.net/user/login.xml?name=USERNAME_HERE&password=PASSWORD_HERE

Please be aware of the security risks involved in sending your API key through an unencrypted channel. Although your API key is not your password, it retains many of the same access rights as your password. Like your password, do not give it out to anyone.

 
 

Posts

[ Return to top ↑ ]
Create | Update | Show | Check MD5 | Tags | List | Flag | Destroy | Deleted Index | Popular | Revert Tags | Vote

Create

[ Return to category top ↑ ]

The base URL is /post/create.xml. There are only four mandatory fields: you need to supply the tags, and you need to supply the file, either through a multipart form or through a source URL. A source, even if blank, and a rating are also required.

  • post[tags] A space delimited list of tags.
  • post[file] The file data encoded as a multipart form.
  • post[rating] The rating for the post. Can be: safe, questionable, or explicit.
  • post[upload_url] If this is a URL, e621 will download the file.
  • post[source] This will be used as the post's 'Source' text. Separate multiple URLs with %0A (url-encoded newline) to define multiple sources. Limit of five URLs
  • post[description] The description for the post.
  • post[is_rating_locked] Set to true to prevent others from changing the rating.
  • post[is_note_locked] Set to true to prevent others from adding notes.
  • post[parent_id] The ID of the parent post.
  • md5 Supply an MD5 if you want e621 to verify the file after uploading. If the MD5 doesn't match, the post is destroyed.

If the call fails, the following response reasons are possible:

  • MD5 mismatch This means you supplied an MD5 parameter and what e621 got doesn't match. Try uploading the file again.
  • duplicate This post already exists in e621 (based on the MD5 hash). An additional attribute called location will be set, pointing to the (relative) URL of the original post.
  • other Any other error will have its error message printed.

If the post upload succeeded, you'll get an attribute called location in the response pointing to the relative URL of your newly uploaded post.

Update

[ Return to category top ↑ ]

The base URL is /post/update.xml. Only the id parameter is required. Leave the other parameters blank if you don't want to change them. If submitting the post[tags] parameter, it is recommended to include the post[old_tags] parameter as well because it allows e621 to correctly handle simultaneous edits from multiple users.

  • id The ID number of the post to update.
  • post[tags] A space delimited list of tags.
  • post[old_tags] A space delimited list of tags. Should include the same tags submitted to post[tags] minus any intended changes. Does nothing without post[tags].
  • post[rating] The rating for the post. Can be: safe, questionable, or explicit.
  • post[source] This will be used as the post's 'Source' text. Separate multiple URLs with %0A (url-encoded newline) to define multiple sources. Limit of five URLs
  • post[description] This will be used as the post's 'Description' text.
  • post[is_rating_locked] Set to true to prevent others from changing the rating.
  • post[is_note_locked] Set to true to prevent others from adding notes.
  • post[parent_id] The ID of the parent post.
  • reason The reason for the submitted changes. Inline DText allowed.

Show

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URL is /post/show.xml. You must supply either the id or md5 attribute.

  • id The ID number of the post to retrieve.
  • md5 The MD5 hash of the post to retrieve.

Returns:

  • id The ID of the post
  • author Username of the user who uploaded the post
  • creator_id User ID of the user who uploaded the post
  • created_at When the post was uploaded
  • status Post status, one of: active, flagged, pending, deleted
  • source The post's source (if there are multiple sources, only the first one is returned
  • sources An array of the post's sources
  • tags The post's tags
  • artist A HTML-escaped JSON array of the post's artist tag(s). Use something like PHP's html_entity_decode() to decode the HTML string, then json_decode() to convert the JSON string to an array.
  • description The post's description
  • fav_count The number of users who have the post in their favorites
  • score The post's score
  • rating The post's rating. One of: e, q, s
  • parent_id If the post has a parent, the ID of the parent post
  • has_children If the post has any children
  • children Comma-separated list of post IDs of this post's children
  • has_notes If the post has any notes
  • has_comments If the post has any comments
  • md5 The post's MD5 hash
  • file_url Absolute URL of the filename
  • file_ext The post's extension. One of: jpg, png, gif, swf, webm
  • file_size Size (in bytes) of the post
  • width Height of the image
  • height Height of the image
  • sample_url Absolute URL of the sample (scaled) filename
  • sample_width Height of the sample (scaled) image
  • sample_height Height of the sample (scaled) image
  • preview_url Absolute URL of the preview (thumbnail) filename
  • preview_width Height of the preview (thumbnail) image
  • preview_height Height of the preview (thumbnail) image
  • delreason Reason the post was deleted. Only appears on posts that have been deleted before.

Note: the following fields are not available for deleted posts: source, sources, md5, file_size, file_ext, preview_width, preview_height, sample_url, sample_width, sample_height, has_children, children

Check MD5

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URL is /post/check_md5.xml.

  • md5 The MD5 hash of the file to look for.

Returns:

  • md5 The same value you supplied.
  • exists A boolean indicating if the file exists. false means that the file has either never been uploaded to e621 or has since been deleted.
  • post_id The ID of the post. Returned only if the file exists.

Tags

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URL is /post/tags.xml. You must supply either the id or md5 attribute.

  • id The ID number of the post to retrieve tag information about.
  • md5 The MD5 hash of the post to retrieve tag information about.

Returns an array of tags, each with the following attributes:

  • name The tag's name
  • id The tag's id
  • count Number of posts that contain the tag
  • type An integer representation of the tag's type. Types are as follows:
    • 0 General
    • 1 Artist
    • 3 Copyright
    • 4 Character
    • 5 Species

List

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URL is /post/index.xml. Deleted posts are not returned. The most efficient method to iterate a large number of posts is to use before_id starting at the highest ID, and then successively request the lowest ID returned each time. When iterating using page, posts will shift between pages if posts meeting the tags search criteria are deleted or added to the site between requests.

  • limit How many posts you want to retrieve. There is a hard limit of 320 posts per request. Defaults to the value set in user preferences.
  • before_id Returns the next [limit] posts with IDs lower than the given ID.
  • page Paginates the search query into pages of length [limit]* and returns the given page. If before_id is supplied, this does nothing.
  • tags The tag search query. Any tag combination that works on the website will work here.

*Deleted posts still count towards the number of posts returned in page requests if 'status:any' or 'status:deleted' is part of the tags search criteria. Deleted posts are not returned either way. JSON requests do not report any post count.
Sorting results with 'order:' using tags does nothing in conjunction with before_id.

Flag

[ Return to category top ↑ ]

The base URL is /post/flag.xml. The id and flag_option parameters are required.

  • id The ID number of the post to flag for deletion.
  • inferior_parent The ID number of the post which is superior to the post being flagged. For duplicates, this should be the ID of the post which is older. Use only when flag_option is set to inferior.
  • flag_option Indicates the reason the post should be deleted. Valid values are:
    • uploader Uploader requests deletion
    • inferior Repost/inferior version of existing post
    • 1 Artist is on avoid-posting list
    • 2 Post is paysite material
    • 3 Uncredited trace
    • 4 Real-life pornography
    • 5 File corrupted
    • 6 Image previously deleted

Destroy

[ Return to category top ↑ ]

The base URL is /post/destroy.xml. Both the id and reason parameters are required. The mode parameter is only required (to be 1) if you are attempting to permanently destroy the post (which must be called a second time, after the post has been normally deleted). You must be logged in to use this action. You must also be janitor or higher.

  • id The ID number of the post to delete.
  • reason The reason you are deleting the post.
  • mode Set to 1 if you are attempting to permanently destroy this post (will only work if called on an already deleted post).

Deleted Index

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URL is /post/deleted_index.xml.

  • user_id Returns posts uploaded by the user with the given ID number.
  • page The page number.

Popular

[ Return to category top ↑ ][ Example XML output ][ Example JSON output ]

The base URLs are /post/popular_by_day.xml, /post/popular_by_week.xml, and /post/popular_by_month.xml.

Revert Tags

[ Return to category top ↑ ]

This action reverts a post to a previous set of tags. The base URL is /post/revert_tags.xml.

  • id The post ID number to update.
  • history_id The ID number of the tag history.

Vote

[ Return to category top ↑ ]

This action lets you vote for a post. You can only vote once per post per IP address. The base URL is /post/vote.xml.

  • id The post ID number to update.
  • score Set to 1 to vote up and -1 to vote down. All other values will be ignored.

If the call did not succeed, the following reasons are possible:

  • already voted You have already voted for this post.
  • invalid score You have supplied an invalid score.

Tags

[ Return to top ↑ ]

List

[ Example XML output ][ Example JSON output ]

The base URL is /tag/index.xml.

  • limit How many tags to retrieve. There is a hard limit of 1000 tags per request. For privileged users and above, setting this to 0 will return every tag.
  • page The page number.
  • order Can be date, count, or name.
  • after_id Return all tags that have an ID number greater than this.
  • name The exact name of the tag.
  • name_pattern Search for any tag that has this parameter in its name.

Show

[ Example XML output ][ Example JSON output ]

The base URL is /tag/show.xml.

  • id The ID of the tag.

Update

The base URL is /tag/update.xml.

  • name The name of the tag to update.
  • tag[tag_type] The tag type. General: 0, artist: 1, copyright: 3, character: 4, species: 5.
  • tag[is_ambiguous] Whether or not this tag is ambiguous. Use 1 for true and 0 for false.

Related

[ Example XML output ][ Example JSON output ]

The base URL is /tag/related.xml.

  • tags The tag names to query.
  • type Restrict results to this tag type (can be general, artist, copyright, character, or species).

Aliases

[ Return to top ↑ ]

This section is incomplete.

List

[ Example XML output ][ Example JSON output ]

The base URL is /tag_alias/index.xml.

  • page The page number.
  • order Can be tag, aliasedtag, reason, user, date, or forum_post.
  • query/aliased_to Search for aliases that have this parameter in its name.
  • user Username of user who submitted the suggestion.
  • approved Can be all, true, false.
  • forum_post Has an accompanying forum post. Can be all/true/false.

Implications

[ Return to top ↑ ]

This section is incomplete.

List

[ Example XML output ][ Example JSON output ]

The base URL is /tag_implication/index.xml.

  • page The page number.
  • order Can be tag, impliedtag, reason, user, date, or forum_post.
  • query/implied_to Search for implications that have this parameter in its name.
  • user Username of user who submitted the suggestion.
  • approved Can be all, true, false.
  • forum_post Has an accompanying forum post. Can be all/true/false.

Artists

[ Return to top ↑ ]

List

[ Example XML output ][ Example JSON output ]

The base URL is /artist/index.xml.

  • name The name (or a fragment of the name) of the artist or the artist URL.
  • limit How many records per page.
  • order Can be date or name.
  • page The page number.

Create

The base URL is /artist/create.xml.

  • artist[name] The artist's name.
  • artist[urls] A list of URLs associated with the artist, whitespace delimited.
  • artist[group_name] The group or circle that this artist is a member of. Simply enter the group's name.
  • artist[other_names] List of comma separated names this artist is also known by.

Update

The base URL is /artist/update.xml. Only the id parameter is required. The other parameters are optional.

  • id The ID of the artist to update.
  • artist[name] The artist's name.
  • artist[urls] A list of URLs associated with the artist, whitespace delimited.
  • artist[is_active] Whether or not the artist is active.
  • artist[group_name] The group or circle that this artist is a member of. Simply enter the group's name.
  • artist[other_names] List of comma separated names this artist is also known by.

Destroy

The base URL is /artist/destroy.xml. You must be logged in to delete artists.

  • id The ID of the artist to destroy.

Comments

[ Return to top ↑ ]

Show

[ Example XML output ][ Example JSON output ]

The base URL is /comment/show.xml. This retrieves a single comment.

  • id The ID number of the comment to retrieve.

List

[ Example XML output ][ Example JSON output ]

This section is incomplete.

The base URL is /comment/index.xml. A maximum of 25 comments are retrieved per request. If you don't specify any parameters you'll get a list of the most recent comments.

  • post_id The ID number of the post to retrieve comments for.
  • page The page number.
  • status Returns hidden comments when set to hidden, visible comments when set to active, or both when set to any. Note that whether or not you can see other user's hidden comments is affected by your permission levels.

Search

[ Example XML output ][ Example JSON output ]

The base URL is /comment/search.xml. A maximum of 25 comments are retrieved per request. If you don't specify any parameters you'll get a list of the most recent comments.

  • query Returns comments which contain the given text.
  • results Affects how query is handled??? Can be either fuzzy or exact
  • date_start Returns comments that were created on or after the given date. Format is yyyy-mm-dd.
  • date_end Returns comments that were created before the given date. Format is yyyy-mm-dd.
  • order Sorts the results. Can be one of the following:
    • date
    • date_asc
    • score
    • score_asc
  • post_id The ID number of the post to retrieve comments for.
  • page The page number.
  • user Returns comments created by the user with the given username.
  • user_id Returns comments created by the user with the given ID number. Takes precedence over user.
  • status Returns hidden comments when set to hidden, visible comments when set to active, or both when set to any. Note that whether or not you can see other user's hidden comments is affected by your permission levels.

Create

The base URL is /comment/create.xml.

  • comment[anonymous] Set to 1 if you want to post this comment anonymously.
  • comment[post_id] The post ID number to which you are responding.
  • comment[body] The body of the comment.

Update

The base URL is /comment/update.xml. Depending on your permission level, comments may only be editable for the first 5 minutes after they are created.

  • id The ID number of the comment being edited.
  • comment[body] The body of the comment.

Destroy

The base url is /comment/destroy.xml. You must be logged in to use this action. You must also be the owner of the comment, or you must be a moderator.

  • id The ID number of the comment to delete.

Hide

The base URL is /comment/hide.xml.

  • id Hides the comment with the given ID number.

Unhide

The base URL is /comment/unhide.xml.

  • id Unhides the comment with the given ID number.

Vote

The base URL is /comment/vote.xml. This action requires an AJAX-like call. That is, your request header must contain X-Requested-With: XMLHttpRequest

  • id Vote on the comment with the given ID number.
  • score
    • up
    • down

To remove a vote, send a request using the same score given previously (e.g. if it was voted up, vote up again to return to neutral).

Blips

[ Return to top ↑ ]

Create

The base URL is /blip/create.xml.

  • blip[body] The blip's content.
  • blip[response] Blip ID number of the blip that the new blip is in response to, if any.

Update

The base URL is /blip/update.xml.

  • id The ID number of the blip being edited.
  • blip[body] The blip's content.

List

[ Example XML output ][ Example JSON output ]

The base URL is /blip/index.xml. If you don't specify any parameters you'll get a list of the most recent blips.

  • name Return blips created by the user with the given name
  • body Returns blips that contain the given string
  • page The page number.
  • limit How many blips to retrieve. Hard limit of 100.
  • status Returns hidden blips when set to hidden, visible blips when set to active, or both when set to any. Note that whether or not you can see other user's hidden blips is affected by your permission levels.
  • response_to ID number of a blip. Returns blips which are in response to the blip with the given ID.

Show

[ Example XML output ][ Example JSON output ]

The base URL is /blip/show.xml.

  • id Returns the blip with the given ID number

Hide

The base URL is /blip/hide.xml.

  • id Hides the blip with the given ID number.

Unhide

The base URL is /blip/unhide.xml.

  • id Unhides the blip with the given ID number.

Wiki

[ Return to top ↑ ]

All titles must be exact (but case and whitespace don't matter).

List

The base URL is /wiki/index.xml. This retrieves a list of every wiki page.

  • order How you want the pages ordered. Can be: title, date.
  • limit The number of pages to retrieve.
  • page The page number.
  • query A word or phrase to search for.

Create

The base URL is /wiki/create.xml.

  • wiki_page[title] The title of the wiki page.
  • wiki_page[body] The body of the wiki page.

Update

The base URL is /wiki/update.xml. Potential error reasons: "Page is locked"

  • title The title of the wiki page to update.
  • wiki_page[title] The new title of the wiki page.
  • wiki_page[body] The new body of the wiki page.

Show

The base URL is /wiki/show.xml. Potential error reasons: "artist type"

  • title The title of the wiki page to retrieve.
  • version The version of the page to retrieve.

Destroy

The base URL is /wiki/destroy.xml. You must be logged in as a moderator to use this action.

  • title The title of the page to delete.

Lock

The base URL is /wiki/lock.xml. You must be logged in as a moderator to use this action.

  • title The title of the page to lock.

Unlock

The base URL is /wiki/unlock.xml. You must be logged in as a moderator to use this action.

  • title The title of the page to unlock.

Revert

The base URL is /wiki/revert.xml. Potential error reasons: "Page is locked"

  • title The title of the wiki page to update.
  • version The version to revert to.

History

The base URL is /wiki/history.xml.

  • title The title of the wiki page to retrieve versions for.

Recent Changes

The base URL is /wiki/recent_changes.xml.

  • user_id
  • page

Notes

[ Return to top ↑ ]

List

The base URL is /note/index.xml.

  • post_id The post ID number to retrieve notes for.

Search

The base URL is /note/search.xml.

  • query A word or phrase to search for.

History

The base URL is /note/history.xml. You can either specify id, post_id, user_id, or nothing. Specifying nothing will give you a list of every note version.

  • limit How many versions to retrieve.
  • page The offset.
  • post_id The ID number of the post to retrieve note versions for.
  • id The ID number of the note to retrieve versions for.
  • user_id Returns notes created by the user with the given ID number.

Revert

The base URL is /note/revert.xml. Potential error reasons: "Post is locked"

  • id The ID of the note to update.
  • version The version to revert to.

Create/Update

The base URL is /note/update.xml. Notes differ from the other controllers in that the interface for creation and updates is the same. If you supply an id parameter, then e621 will assume you're updating an existing note. Otherwise, it will create a new note. Potential error reasons: "Post is locked"

  • id If you are updating a note, this is the ID number of the note to update.
  • note[post_id] The ID number of the post this note belongs to.
  • note[x] The x coordinate of the note.
  • note[y] The y coordinate of the note.
  • note[width] The width of the note.
  • note[height] The height of the note.
  • note[is_active] Whether or not the note is visible. Set to 1 for active, 0 for inactive.
  • note[body] The note message.

Users

[ Return to top ↑ ]

List

[ Example XML output ][ Example JSON output ]

The base URL is /user/index.xml. If you don't specify any parameters you'll get a listing of all users.

  • id The ID number of the user.
  • name Text matching part or all of a user's name.
  • level Permission level. Can be one of the following or use -1 for Any:
    • 0 Unactivated
    • 10 Blocked
    • 20 Member
    • 30 Privileged
    • 33 Contributor
    • 34 Former Staff
    • 35 Janitor
    • 40 Mod
    • 50 Admin
  • order Sort order. Can be one of the following:
    • name Username, based on Unicode values (ascending)
    • posts Uploaded post count (descending)
    • deleted Deleted post count (descending)
    • notes Note edit count (descending)
    • tagedits Tag edit count (descending)
    • date Join date from most recent to least
    • record Cumulative user record score (descending)

Returns:
An array of users whose ID exactly matches the supplied id attribute or whose name contains the supplied name attribute. Each user element has the following attributes:

  • name The name of the user.
  • id The ID number of the user.
  • level The permission level of the user. See list under level parameter above for possible values.
  • created_at When the user created their account.
  • avatar_id The ID number of the post the user is currently using as their avatar, if any.
  • stats An XML child element or JSON object with the following attributes:
    • post_count
    • del_post_count
    • edit_count The number of tag edits the user has made.
    • favorite_count
    • wiki_count
    • forum_post_count
    • note_count
    • comment_count
    • blip_count
    • set_count
    • pool_update_count
    • pos_user_records
    • neutral_user_records
    • neg_user_records
  • subscriptions User tag subscriptions, if any. In JSON responses this is represented by a subscriptions object. In XML responses it is represented by one or more subscription child elements.
  • artist_tags Artist tags associated with the user. Represented by a child element in XML responses or an array in JSON responses.

Show

[ Example XML output ][ Example JSON output ]

The base URL is /user/show.xml. If you don't specify any parameters you'll get the currently logged in user.

  • id The ID number of the user.
  • name Text exactly matching a user's name.

Returns:
The same attributes given by the List function above, but only for a single user.

User Records

[ Return to top ↑ ]

Show

[ Example XML output ][ Example JSON output ]

The base URL is /user_record/show.xml.

  • id The ID number of the user record.

Dmail

[ Return to top ↑ ]

Create

The base URL is /dmail/create.xml.

  • dmail[parent_id] Dmail ID number of the dmail that the new dmail is in response to, if any.
  • dmail[to_name]
  • dmail[title]
  • dmail[body]

List

[ Example XML output ][ Example JSON output ]

The base URL is /dmail/inbox.xml. If you don't specify any parameters you'll get a list of the most recently sent and received dmails, excluding hidden dmails.

  • from_name Returns dmails sent from the user with the given username.*
  • to_name Returns dmails sent to the user with the given username.*
  • title Returns dmails with titles which contain the given string.
  • date_start Returns dmails sent on or after the given date. Format is yyyy-mm-dd.
  • date_end Returns dmails sent before the given date. Format is yyyy-mm-dd.
  • show Returns incoming dmails when set to in, outgoing dmails when set to out, or both when set to all. Defaults to the setting last used through the site's normal interface.
  • visibility Returns hidden dmails when set to hidden, visible dmails when set to unhidden, or both when set to all.
  • page Page number to retrieve in the paginated results.

*If the inbox does not contain any dmails with the given username, this parameter will be ignored. Thus it is not safe to rely on this function to return dmails from/to specific users. The dmails returned should be checked individually for the desired senders/recipients.

Show

The base URL is /dmail/show.xml.

  • id Returns the dmail with the given ID number.

Hide

The base URL is /dmail/hide.xml.

  • id Hides the dmail with the given ID number.

Unhide

The base URL is /dmail/unhide.xml.

  • id Unhides the dmail with the given ID number.

Hide All

The base URL is /dmail/hide_all.xml.

Hides all dmails in the inbox.

Unhide All

The base URL is /dmail/unhide_all.xml.

Unhides all dmails in the inbox.

Mark All Read

The base URL is /dmail/mark_all_read.xml.

Marks all dmails in the inbox as read.

Forum

[ Return to top ↑ ]

Create

The base URL is /forum/create.xml.

  • forum_post[body]
  • forum_post[title]
  • forum_post[parent_id]
  • forum_post[category_id] Can be one of the following:
    • 1 General
    • 11 Site Bug Reports & Feature Requests
    • 2 Tag Alias and Implication Suggestions
    • 10 Tag/Wiki Projects and Questions
    • 3 Art Talk
    • 5 Off Topic
    • 9 e621 Tools and Applications

Update

The base URL is /forum/update.xml.

  • id The ID number of the forum post being edited.
  • forum_post[body]
  • forum_post[title]
  • forum_post[category_id] See Create for possible values.

List

[ Example XML output ][ Example JSON output ]

The base URL is /forum/index.xml. If you don't specify any parameters you'll get a list of all the parent topics.

  • parent_id The parent ID number.
  • page The page.
  • limit How many posts to retrieve. Hard limit of 100.

Search

[ Example XML output ][ Example JSON output ]

The base URL is /forum/search.xml. If you don't specify any parameters you'll get a list of all the parent topics.

  • query Returns posts which contain the given text. Using the prefix user: allows for searching for posts created by a given user.
  • page The page.

Show

[ Example XML output ][ Example JSON output ]

The base URL is /forum/show.xml.

  • id Returns the post with the given ID number.

Hide

The base URL is /forum/hide.xml. Unlike the other hide methods, requires a POST call.

  • id Hides the forum post with the given ID number.

Unhide

The base URL is /forum/unhide.xml.

  • id Unhides the forum post with the given ID number.

Pools

[ Return to top ↑ ]

List Pools

The base URL is /pool/index.xml. If you don't specify any parameters you'll get a list of all pools.

  • query The title.
  • page The page.

List Posts

The base URL is /pool/show.xml.

  • id The pool ID number.
  • page The page.

Update

The base URL is /pool/update.xml.

  • id The pool ID number.
  • pool[name] The name.
  • pool[is_locked] 1 or 0, whether or not the pool is locked. Mod+ only function.
  • pool[description] A description of the pool.

Create

The base URL is /pool/create.xml.

  • pool[name] The name.
  • pool[is_locked] 1 or 0, whether or not the pool is locked. Mod+ only function.
  • pool[description] A description of the pool.

Destroy

The base URL is /pool/destroy.xml.

  • id The pool ID number.

Add Post

The base URL is /pool/add_post.xml. Potential error reasons: "Post already exists", "access denied"

  • pool_id The pool to add the post to.
  • post_id The post to add.

Remove Post

The base URL is /pool/remove_post.xml. Potential error reasons: "access denied"

  • pool_id The pool to remove the post from.
  • post_id The post to remove.

Sets

[ Return to top ↑ ]
List | Show | Create | Update | Add Post | Remove Post | Destroy | Maintainers

List

[ Return to category top ↑ ]

The base URL is /set/index.xml

  • page The page number (50 sets per page)
  • user_id Only show sets owned by the given user
  • maintainer_id Only show sets maintained by the given user
  • post_id Only show sets containing the given post

Returns:

  • sets
    • set
      • created-at
      • updated-at
      • id
      • user-id
      • name
      • shortname
      • description
      • public
      • post-count
      • transfer-to-parent-on-delete

Show

[ Return to category top ↑ ]

The base URL is /set/show.xml

  • id The ID number of the set to retrieve

Returns:

  • post-set
    • created-at
    • updated-at
    • id
    • user-id
    • name
    • shortname
    • description
    • public
    • post-count
    • transfer-to-parent-on-delete
    • posts
      • post

Create

[ Return to category top ↑ ]

The base URL is /set/create.xml

  • set[name] The name of the set
  • set[shortname] The short name of the set
  • set[description] The description of the set
  • set[public] Whether to make the set public (true) or private (false)
  • set[transfer_to_parent_on_delete] Whether to replace deleted posts with their parents

Update

[ Return to category top ↑ ]

The base URL is /set/update.xml

  • set[id] ID of the set to update
  • set[name] The name of the set
  • set[shortname] The short name of the set
  • set[description] The description of the set
  • set[public] Whether to make the set public (true) or private (false)
  • set[transfer_to_parent_on_delete] Whether to replace deleted posts with their parents

Add Post

[ Return to category top ↑ ]

The base URL is /set/add_post.xml

  • set_id ID of the set to add a post to
  • post_id ID of the post to add

Remove Post

[ Return to category top ↑ ]

The base URL is /set/remove_post.xml

  • set_id ID of the set to remove a post from
  • post_id ID of the post to remove

Destroy

[ Return to category top ↑ ]

The base URL is /set/destroy.xml

  • id The name of the set to destroy

 

Maintainers

[ Return to category top ↑ ]

List

Use this to view maintainers/invites for a given set. The base URL is /set/maintainers.xml

  • id The name of the set to retrieve

Returns:

  • set-maintainers
    • set-maintainer
      • id
      • post-set-id
      • user-id
      • status - Either "pending", "approved", or "blocked"

List Invites

Use this to view your personal invites. The base URL is /set_maintainer/index.xml

Returns:

  • invites
    • invite
      • id
      • post-set-id
      • user-id
      • status - Either "pending", "approved", or "blocked"

Create Maintainer

The base URL is /set_maintainer/create.xml

  • username / user_id The username or user ID of the maintainer to add
  • set_id The ID of the set to add the maintainer to

Destroy Maintainer

The base URL is /set_maintainer/destroy.xml. You must supply the id, user_id or username of the maintainer. user_id and username must be accompanied by a set_id.

  • id The ID of the maintainer to destroy
  • username The username of the maintainer to destroy
  • user_id The user ID of the maintainer to destroy
  • set_id The ID of the set

Approve/Deny/Block Maintainer Invite

The base URL is /set_maintainer/approve.xml (or deny.xml, or block.xml). You must supply either id or set_id.

  • id The ID of the maintainer invite to approve/deny/block
  • set_id The ID of the set to approve/deny/block the invite to

Favorites

[ Return to top ↑ ]

List Users

The base URL is /favorite/list_users.json. There is no XML API for this action.

  • id The post id.

Tag History

[ Return to top ↑ ]

List

The base URL is /post_tag_history/index.xml. Due to performance issues, this controller does not use page numbers. Instead, it takes an ID and returns the next/previous [limit] results. To traverse forward (back in time) through multiple pages of results, set the after parameter of the next request to the ID of the last result in the current result set. Or to go backwards (towards more recently) through results, set before to the ID of the first result in the current result set.

  • post_id Filter by post ID.
  • date_start Show only edits after this date (inclusive). Takes most date formats, including 10-digit UNIX timestamps
  • date_end Show only edits before this date (inclusive). Takes most date formats, including 10-digit UNIX timestamps
  • user_id Filter by user ID.
  • user_name Filter by username. Must match exactly, case insensitive.
  • source Filter by source. Wildcard, so 'example' will match 'http://www.example.com/'
  • tags Filter by tags. Wildcard, like above. Caveat: since this is a simple text match against the history entry's tag list, it's best to only use one tag for this field.
  • reason Filter by edit reason. Wildcard, like above.
  • description Filter by description. Wildcard, like above.
  • limit How many results to return at once. Defaults to 100 and limited to 1000.
  • before / after Show the next [limit] results before (higher ID than) or after (lower ID than) the given ID.

Flag History

[ Return to top ↑ ]

List

The base URL is /post_flag_history/index.xml.

  • post_id The post id.
  • user_id The user id.
  • username The user name.

Tickets

[ Return to top ↑ ]

Create

The base URL is /ticket/create.xml.

  • ticket[qtype] The type of ticket being created. Can be one of the following:
    • user User complaint
    • dmail Private message complaint
    • comment Comment complaint
    • forum Forum post complaint
    • blip Blip complaint
    • wiki Wiki complaint
    • namechange Username change
  • ticket[disp_id] ID number of the object being reported. For namechange, use the user's own ID.
  • ticket[reason] Text describing the reason the ticket is being created. For namechange this should only contain the desired username.

Usernames must conform to the following restrictions:

  • 20 characters max
  • Can contain:
    • Non-accented letters, uppercase and lowercase (A-Z)
    • Numbers (0-9)
    • The following symbols: -_~'

List

[ Example XML output ][ Example JSON output ]

The base URL is /ticket/index.xml. If you don't specify any parameters you'll get a list of the most recent tickets.

  • type Returns tickets of the given type. Can be one of the following:
    • any Any
    • user User complaint
    • dmail Private message complaint
    • comment Comment complaint
    • forum Forum post complaint
    • blip Blip complaint
    • wiki Wiki complaint
    • namechange Username change
  • status Returns tickets with the given status. Can be one of the following:
    • any Any
    • approved Approved/investigated
    • partial Under investigation
    • pending Pending
    • denied Denied
  • user_id Returns tickets created by the user with the given ID number.
  • page Page number to retrieve in the paginated results.

Show

[ Example XML output ][ Example JSON output ]

The base URL is /ticket/show.xml.

  • id Returns the ticket with the given ID number.

[Back: e621:index]