MODERN PASTE API


The documentation that follows describes the JSON-based, HTTP API used to interface directly with Modern Paste'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 Modern Paste 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


Modern Paste 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


https://paste.fedoraproject.org/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
deactivation_token string Token used for deactivating the paste

SAMPLE USAGE


import requests

resp = requests.post(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/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


https://paste.fedoraproject.org/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(
    'https://paste.fedoraproject.org/api/paste/top',
    json={ 
        'page_num': '0',
        'num_per_page': '20',
    },
)
assert resp.status_code == 200