API DOCUMENTATION
Interface with vx.cx's backend programmatically in your apps
ENDPOINTS
MODERN PASTE API
The documentation that follows describes the JSON-based, HTTP API used to interface directly with
vx.cx's Python backend. Below, each API is listed with its action, description, endpoint URL,
required request parameters, response data, and example request executed from a Python client.
All endpoints will respond only to the HTTP POST verb, with the
application/json content type with key-value pairs for
the request parameters (as applicable).
AUTHENTICATION
There are three types of API endpoints: those that require authentication, those that can optionally
be authenticated for slightly modified behavior, and those for which no authentication is required.
Authentication-sensitive endpoints are labeled as authentication required
and authentication optional.
Endpoints for which no authentication is required can be requested directly with no additional required
action or parameters. Endpoints that require authentication (or those that optionally allow
authentication, and you would like to authenticate) must be authenticated with an API key.
In your POST request to the authentication-sensitive endpoint, include an additional key-value
pair in your JSON request parameters to authenticate the request via an API key. The key name is
api_key, and its value is the API key of the user for
which the request should be authenticated. Note that using the API key is, to the application, logically
equivalent to being logged in via the web interface.
The following is a Python example of how you might access the authentication-sensitive paste creation
endpoint when vx.cx is hosted on the server at localhost:5000.
import requests
# Create a new paste tied with an existing user account
resp = requests.post(
'http://localhost:5000/api/paste/submit',
json={
'contents': 'test paste',
'api_key': 'BbK1F09sZZXL2335iqDGvGeQswQUcvUmzxMoWjp3yvZDxpWwRiP4YQL6PiUA8gy2',
},
)
assert set(resp.json().keys()) == {
'post_time',
'expiry_time',
'language',
'title',
'views',
'is_active',
'paste_id_repr',
'contents',
}
GENERIC ERROR RESPONSES
vx.cx has a set of generic JSON responses to requests that are either invalid or result in an error that can be resolved on the client side. An error condition occurs when the HTTP status code is not 200, or when the success key in the response JSON is false. These failure names and descriptions are tabulated below.
| FAILURE NAME | DESCRIPTION |
| auth_failure | This error is returned when attempting to access an authentication-required endpoint without authentication, or when attempting to access an authentication-optional endpoint with an invalid API key. |
| incomplete_params_failure | At least one required request parameter for the endpoint is missing from the request. Even if all required parameters are supplied as keys, this error may still be returned if the value of one of the required parameters is blank (e.g., an empty string). This error may also be returned if the Content-Type of the request isn't explicitly specified as application/json. |
| nonexistent_user_failure | The endpoint attempted to execute actions on a user that does not exist, or is no longer active. |
| nonexistent_paste_failure | The endpoint attempted to execute actions on a paste that does not exist, or is no longer active. |
| undefined_failure | The server encountered an undefined error (usually related to the database). No client-side actions can be taken to resolve the problem. |
| unauthenticated_pastes_disabled_failure | The server administrator has required that users be signed in to post new pastes. You must authenticate this request with an API key. |
| user_registration_disabled_failure | The server administrator has disabled new user registration. |
| paste_attachments_disabled_failure | The server administrator has disabled paste attachments, and the action attempted to add an attachment to a paste. Repeating the same request without any attachments will succeed. |
| paste_attachment_too_large_failure | The uploaded paste attachment is larger than that allowed by the server. |
CREATE NEW PASTE AUTHENTICATION OPTIONAL
Create a new anonymous or authorized paste
Post a new paste, optionally tied to an existing user account. If the endpoint is authenticated with an API key, the paste will be posted under the user account associated with the API key. If no authentication is provided, the post will be posted anonymously. The endpoint exposes the same options available to the main web interface, including specifying the paste title, expiry, password, and language. Full details on required and optional request parameters are detailed below.
ENDPOINT
http://vx.cx/api/paste/submit
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| contents | string | Paste contents |
| expiry_time | number | Unix timestamp at which the paste should expire; defaults to no expiry if no value is supplied (optional) |
| title | string | Paste title; defaults to Untitled if no value is supplied (optional) |
| language | string | Language of the paste; defaults to plain text if no value is supplied (optional) |
| password | string | Optionally add a password to restrict access to the paste; defaults to no password if no value is supplied (optional) |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| post_time | number | Unix timestamp at which the paste was posted |
| expiry_time | number | Request input callback |
| language | string | Request input callback |
| title | string | Request input callback |
| views | number | The number of views the paste has; initialized to 0 |
| is_active | boolean | This field will always be true for a new paste. |
| is_password_protected | boolean | Whether the paste is protected by a password. |
| paste_id_repr | number/string | The paste ID, represented as either a decrypted or encrypted ID (this is configured by the server administrator) |
| contents | string | Request input callback |
| url | string | Full URL to the web interface for viewing the paste |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/submit',
json={
'contents': 'test paste',
'expiry_time': '1453355837',
'title': 'Paste title',
'language': 'python',
'password': 'password123',
},
)
assert resp.status_code == 200
GET PASTE DETAILS AUTHENTICATION OPTIONAL
Get details for an existing paste
Retrieve publicly accessible details for an existing, active paste, queried by paste ID. The paste ID will either be an encrypted string (if the server administrator has enabled this option), or a regular decrypted interger. For password-protected pastes, you must supply the password request parameter, containing a plain-text representation of the paste's password.
ENDPOINT
http://vx.cx/api/paste/details
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| paste_id | number/string | Paste ID |
| password | string | Plain-text password of the paste, if it is password-protected. If the paste requested is password-protected, failing to provide this option will result in the auth_failure error. (optional) |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| post_time | number | Unix timestamp at which the paste was posted |
| expiry_time | number | Unix timestamp at which the paste expires; null if the paste doesn't expire |
| language | string | Language of the paste |
| title | string | Title of the paste |
| views | number | The number of views the paste has |
| is_active | boolean | This field will always be true, since inactive pastes are not returned by this endpoint. |
| is_password_protected | boolean | Whether the paste is protected by a password. |
| paste_id_repr | number/string | Request input callback |
| contents | string | Contents of the paste |
| poster_username | string | Username of poster; 'Anonymous' if posted anonymously |
| url | string | Full URL to the web interface for viewing the paste |
| attachments | array | Array of attachments associated with the paste, each of which has properties file_name (name of the uploaded file), file_size (size of the file in bytes), and mime_type (the MIME type of the file, if available) |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/details',
json={
'paste_id': '5',
'password': 'p4ssw0rd',
},
)
assert resp.status_code == 200
GET PASTES FOR USER AUTHENTICATION REQUIRED
Get all pastes for the authenticated user
Retrieve a list of paste details for the user, authenticated via an API key. The pastes will be returned in an array whose elements have the same key-value pairs as the Paste Details API endpoint.
ENDPOINT
http://vx.cx/api/paste/user
REQUEST PARAMETERS
None
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| pastes | array | Array of paste details. The paste details fields are exactly identical to those returned by the Paste Details API endpoint above. |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/user',
json={
'api_key': 'BbK1F09sZZXL2335iqDGvGeQswQUcvUmzxMoWjp3yvZDxpWwRiP4YQL6PiUA8gy2',
},
)
assert resp.status_code == 200
DEACTIVATE PASTE AUTHENTICATION OPTIONAL
Deactivate an anonymous or authenticated paste
Deactivate an existing paste. You can either deactivate the paste by either (1) supplying the deactivation token associated with the paste without any authentication, or (2) supplying authentication (API key) associated with the account that owns the paste. Note that for (2), the paste must be an authenticated paste (e.g. posted with authentication, and thereby posted to an existing user account). (1) is the only way to deactivate an anonymous paste, but may also be used for authenticated pastes. The paste ID will either be an encrypted string (if the server administrator has enabled this option), or a regular decrypted interger.
ENDPOINT
http://vx.cx/api/paste/deactivate
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| paste_id | number/string | Paste ID |
| deactivation_token | string | Deactivation token associated with the paste, generated when it is first posted. While the endpoint will respond without this field, if attempting to deactivate an anonymous paste, the request will fail if this field is not provided. (optional) |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| paste_id | number/string | Request input callback |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/deactivate',
json={
'paste_id': '5',
'deactivation_token': 'GoX0ik10I6NfTyzQhIHwpPv4O1MQxULhRoCAERjqSNPeOG5TusvlI3lSHqzqc2sW',
},
)
assert resp.status_code == 200
SET PASTE PASSWORD AUTHENTICATION REQUIRED
Set a password on paste posted from a user account
Set or remove a password on a paste that was posted with authentication. You can only modify pastes that the API key-authenticated user owns.
ENDPOINT
http://vx.cx/api/paste/set_password
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| paste_id | number/string | Paste ID |
| password | string/null | The password to set for the paste. You can set this field to an empty string or null to remove the password on the paste (if applicable). |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| paste_id | number/string | Request input callback |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/set_password',
json={
'paste_id': '1',
'password': 'p4ssw0rd',
'api_key': 'BbK1F09sZZXL2335iqDGvGeQswQUcvUmzxMoWjp3yvZDxpWwRiP4YQL6PiUA8gy2',
},
)
assert resp.status_code == 200
GET RECENT PASTES
Retrieve a paged enumeration of recently posted pastes
Query the database for a listing of recent pastes, ordered from most recent to least recent. In order to limit the size of the database query, results are paginated: specify the number of pastes to retrieve per query and specify the page number of the query. Both anonymous and authenticated pastes are returned.
ENDPOINT
http://vx.cx/api/paste/recent
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| page_num | number | Page number of the list for which to retrieve pastes. The first page is 0, and there is no last page (though the endpoint will return empty results if there are no more results to display). |
| num_per_page | number | The number of pastes to retrieve per page. It is recommended to not make this number too large, so to limit the size of the database query. |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| pastes | array | Array of paste details, ordered (descending) by post time. The paste details fields are exactly identical to those returned by the Paste Details API endpoint above. |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/recent',
json={
'page_num': '0',
'num_per_page': '20',
},
)
assert resp.status_code == 200
GET TOP PASTES
Retrieve a paged enumeration of top pastes
Query the database for a listing of most-viewed pastes, ordered from the highest number of views to the least number of views. In order to limit the size of the database query, results are paginated: specify the number of pastes to retrieve per query and specify the page number of the query. Both anonymous and authenticated pastes are returned.
ENDPOINT
http://vx.cx/api/paste/top
REQUEST PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| page_num | number | Page number of the list for which to retrieve pastes. The first page is 0, and there is no last page (though the endpoint will return empty results if there are no more results to display). |
| num_per_page | number | The number of pastes to retrieve per page. It is recommended to not make this number too large, so to limit the size of the database query. |
RESPONSE PARAMETERS
| PARAMETER | TYPE | DESCRIPTION |
| success | boolean | true if the request was successful; false otherwise. |
| message | string/null | null if the request was successful; a short message explaining the error otherwise. |
| failure_name | string | The name of the failure. This field is not present on a successful request. |
| pastes | array | Array of paste details, ordered (descending) by number of views. The paste details fields are exactly identical to those returned by the Paste Details API endpoint above. |
SAMPLE USAGE
import requests
resp = requests.post(
'http://vx.cx/api/paste/top',
json={
'page_num': '0',
'num_per_page': '20',
},
)
assert resp.status_code == 200