Prerequisites

Obtaining your API key

Navigate to your account's API access page to retrieve a newly generated API key which will be tied to your PonyAggregate account. API keys last indefinitely and can only be viewed once. Please ensure to treat your API key as a password as it can be used to authenticate with your account via HTTP requests.

Key-based API access may be revoked at any time by the PonyAggregate moderation team.

Authenticating requests

After obtaining your API key from the appropriate location, store it in a secure location for use with your code (e.g. an environemnt variable), as it can be used to compromise your PonyAggregate account.

Every request made with an API key requires the usage of the Authorization: Bearer <api key> scheme. Session-based cookies are not allowed.

Example cURL request:

API rate limits

API usage guidelines

This section covers some essential information about how to appropriately use the PonyAggregate API without facing account moderation and other penalties.

• Respect rate-limits and do not exceed the rate limit for your user group.
• Do not bypass API rate limits by rotating accounts or session cookies.
• Use a designated, staff-approved bot account for high-volume API interactions such as scraping and mass external imports. Contact us on our Discord server or via email.
• Ensure that submissions and other content uploaded via the API are high-quality and must follow the same content guidelines as if you were on the site.
• Do not automate account flows or mass-create accounts for sockpuppeting or evading rate limits.
• Do not try to circumvent security controls such as Cloudflare Turnstile or role checks.
• Please attempt to cache results to optimize API usage.

Rate limits for API requests

The API request rate limit is currently set to 70 requests every 5 seconds (14 requests per second).

Authentication

Authenticating as a user

The following API endpoint can be used to authenticate as a user given a username and password.

Example request body

{

 "identifier": "username",

 "password": <password>,

 "cfKey": "auth",

 "cfToken": <Cloudflare Turnstile token>

}

Upon successful authentication, a Set-Cookie header will be returned by the server containing a session cookie. Each session cookie expires after exactly 4 months.

Submission endpoints

Creates a new submission with the provided metadata.

Example request body

{

 "name": "Beat It PMV",

 "description": <required field>,

 "tags": ["pmv"],

 "source": "https://www.youtube.com/watch?v=gmJ2Bkx2C5A",

 "attachments": <array of attachment UUIDs>,

 "thumbnailMime": "image/webp",

 "thumbnail": <Base64 encoded string>,

 "rating": <SubmissionRating>,

 "creator": "animated james",

 "submissionType": <SubmissionType>,

 "originalDate": <Unix epoch timestamp>,

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>,

}

Supported submission rating types

• Safe
• Suggestive
• Mature

Supported submission content types

• Photo
• Artwork
• Video
• Aniumation
• Audio
• Music
• Thread
• Fanfic
• Model
• Game
• Other

Imports an image from Derpibooru.org with the specified image ID.

Example request body

{

 "imageId": <image id>, // from https://derpibooru.org/images/<image id>

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>

}

Example response body

{

 "attachment": {

     "uuid": <attachment uuid>,

     "mime": <image MIME type>

 },

 "submission": {

     "name": <image name>,

     "type": <"Artwork" | "Animation">,

     "description": <image description>,

     "rating": <SubmissionRating>,

     "tags": [<image tags>],

     "creatorName": <derpibooru image uploader>,

     "source": "https://derpibooru.org/images/<image id>",

     "originalDate": <derpibooru image date>,

     "thumbnail": <Base64 encoded string of image>,

     "thumbnailMime": <image MIME type>,

 }

}

This endpoint uploads the image directly from Derpibooru to the archive and returns auto-generated submission metadata that resembles the image's metadata on Derpibooru. However, a submission is not actually created, and it is expected that you call /api/submissions/new

Imports an image from Pony.Tube with the specified image ID.

Example request body

{

 "videoId": <video id>, // from https://pony.tube/w/<video id>

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>,

}

Example response body

{

 "attachment": {

     "uuid": <attachment uuid>,

     "mime": <video MIME type>

 },

 "submission": {

     "name": <video name>,

     "type": "Video",

     "tags": ["pony.tube import", <video tags>],

     "description": <video description>,

     "rating": <SubmissionRating>,

     "creatorName": <video uploader username>,

     "source": "https://pony.tube/w/<video id>",

     "originalDate": <video upload date>,

     "thumbnail": <Base64 encoded string of video preview>,

     "thumbnailMime": <MIME type of video preview>

 }

}

Similarly to the Derpibooru import endpoint, this endpoint also returns auto-generated sumbission metadata and imports the highest quality video track available from Pony.Tube. However, you are expected to create the submission via /api/submissions/new

Edits a submission with the specified id

Example request body

{

 "name": <new name>,

 "description": <new description>,

 "tags": [<new tags>],

 "source": <new source>,

 "attachments": [<new attachments>],

 "thumbnailMime": <new thumbnail MIME type>,

 "thumbnail": <new thumbnail>,

 "rating": <new rating: SubmissionRating>,

 "creator": <new creator>,

 "submissionType": <new type: SubmissionType>,

 "originalDate": <new date>,

 "newAttachments": [<new attachment keys>],

 "removedAttachments": [<attachment keys to remove>],

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>,

}

Simply deletes the submission with the specified id. Returns status 200 upon successful deletion.

Attachments

Returns an attachment UUID and presigned URL for attachment uploads.

Example request body

{

 "name": <attachment name>,

 "mime": <attachment MIME type>,

 "size": <attachment size in bytes>,

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>

}

Example response body

{

 "presignedUrl": <presigned url>,

 "uuid": <new attachment UUID>

}

Files can then be uploaded to the presigned url and can be finalized with the server by making a request to /api/attachments/[name]/finalize

Finalizes the attachment upload process after an attachment with a UUID of namewas uploaded to the S3 bucket with the presigned URL returned by /api/attachments/create.

Lists

Creates a new submissions list with the provided metadata.

Example request body

{

 "name": <list name, 1-100 characters>,

 "description": <list description, up to 10,000 characters>,

 "rating": <SubmissionRating>,

 "public": <true | false>,

 "collaborative": <true | false>,

 "collaborativeUsernames": [<usernames list>],

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>

}

Edits the submissions list with the specified id.

Example request body

{

 "name": <new name, 1-100 characters>,

 "description": <new description, up to 10,000 characters>,

 "rating": <new rating: SubmissionRating>,

 "public": <true | false>,

 "collaborative": <true | false>,

 "cfKey": "invisible",

 "cfToken": <Cloudflare Turnstile token>

}

List submissions endpoints

Adding submissions to lists

Example request body

{

 "submissionIds": [<ids>]

}

Removing submissions to lists

Example request body

{

 "submissionIds": [<ids>]

}

List collaborators endpoints

Adding collaborators to lists

Example request body

{

 "collaboratorUsernames": [<usernames>]

}

Removing collaborators to lists

Example request body

{

 "collaboratorUsernames": [<usernames>]

}