Introduction

Welcome to the Paste.ee API! You can use our API to access Paste.ee endpoints, which can get and submit pastes, and various other information like syntaxes.

We currently have no language bindings, if you'd like to submit one, please open an issue on Github

Authentication

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Access-Key: meowmeowmeow"

curl "api_endpoint_here?key=meowmeowmeow"

curl "api_endpoint_here"
  -d "key=meowmeowmeow"

Make sure to replace meowmeowmeow with your API key.

Paste.ee uses Application and User Application keys to allow access to the API. You can register a new Application key at your account api page.

Application keys represent an anonymous paste upload, while User Application keys attach pastes to an account (i.e. your user's account after providing the key).

Paste.ee expects for the API key to be included in all API requests to the server in a header that looks like the following:

X-Auth-Token: meowmeowmeow

Or in a query parameter/request body:

key=meowmeowmeow

Or as the username in basic auth:

Authorization: Basic base64('meowmeowmeow:')

Sections

Sections are containers for paste contents, which contain information about names, syntaxes, and the content itself.

Data structure

Key	Optional	Description
name	true	Section name. Default: New Paste 1-10
syntax	true	Section syntax. Default: autodetect
contents	false	Section contents

Pastes

List pastes

curl "https://api.paste.ee/v1/pastes"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
  "total": 0,
  "per_page": 0,
  "current_page": 0,
  "last_page": 0,
  "next_page_url": "string",
  "prev_page_url": "string",
  "from": 0,
  "to": 0,
  "data": [
    {
      "id": "string",
      "description": "string",
      "views": 0,
      "created_at": "string",
      "sections": [
        {
          "name": "string",
          "syntax": "string",
          "contents": "string"
        }
      ]
    }
  ]
}

This endpoint retrieves all pastes.

You can traverse pages by using next_page_url and prev_page_url. Please, when listing all pastes in an account, increase items per page to a reasonable amount to minimize requests.

HTTP Request

GET https://api.paste.ee/v1/pastes

Query Parameters

Parameter	Default	Description
perpage	25	Items to return per page.
page	1	Page number

Submit a new paste

curl "https://api.paste.ee/v1/pastes"
  -X "POST"
  -H "Content-Type: application/json"
  -H "X-Auth-Token: meowmeowmeow"
  -D '{"description":"test","sections":[{"name":"Section1","syntax":"autodetect","contents":"Testing!"}]}'

The above command returns JSON structured like this:

{
  "id": "<id>",
  "link": "https://paste.ee/p/<id>"
}

This endpoint submits a paste to the database.

HTTP Request

POST https://api.paste.ee/v1/pastes

Accepts data either as application/x-www-form-urlencoded or application/json

Request Body

Parameter	Required	Default	Description
encrypted	No	false	Whether the paste should be treated as encrypted.
description	No	Empty	Overall paste description.
expiration	No	1m	Paste expiration time. Use never to never expire.
sections	Yes	-	Array of sections.

Expiration

Expiration is handled as seconds, or a suffixed string. Only single units are accepted, so you cannot use a combination.

never can be used for no expiration.

Suffix	Unit	Example
d	Days	3d
w	Weeks	4w
m	Months	2m
y	Years	1y

Examples of expirations:

1w = 1 week, 8w = 8 weeks, 4m = 4 months, 2y = 2 years

Submit a new paste with a multipart request/files

curl "https://api.paste.ee/v1/pastes"
  -X "POST"
  -H "X-Auth-Token: meowmeowmeow"
  -F "files[]=@test.txt"
  -F "names[]=test.md"
  -F "syntaxes[]=markdown"

The above command returns JSON structured like this:

{
  "id": "<id>",
  "link": "https://paste.ee/p/<id>"
}

HTTP Request

POST https://api.paste.ee/v1/pastes/file

Request Body

Parameter	Required	Description
files[]	Yes	Array of files
names[]	No	Array of names, can also specify names for only specific files;
syntaxes[]	No	Array of syntaxes, can also specify syntaxes for only specific files.

Get a paste

curl "https://api.paste.ee/v1/pastes/<id>"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
  "success":true,
  "paste": {
    "id":"<id>",
    "encrypted":false,
    "description":"",
    "views":123,
    "created_at":"2015-11-10 22:15:41",
    "expires_at":null,
    "sections":[
      {
        "id":0,
        "syntax":"autodetect",
        "name":"New Paste",
        "contents":"Something meow"
      }
    ]
  }
}

This endpoint gets a paste and it's contents.

HTTP Request

GET https://api.paste.ee/v1/pastes/<id>

Path parameters

Parameter	Description
id	The paste identifier.

Remove a paste

curl "https://api.paste.ee/v1/pastes/<id>"
  -X "DELETE"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
  "success":true
}

This endpoint deletes a paste permanently.

HTTP Request

DELETE https://api.paste.ee/v1/pastes/<id>

Path parameters

Parameter	Description
id	The paste identifier.

Syntaxes

List Syntaxes

curl "https://api.paste.ee/v1/syntaxes"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
   "syntaxes":[
      {
         "id":1,
         "short":"autodetect",
         "name":"Auto Detect"
      },
      {
         "id":2,
         "short":"text",
         "name":"Text"
      }
   ],
   "success":true
}

This endpoint lists available syntaxes.

HTTP Request

GET https://api.paste.ee/v1/syntaxes

Get syntax

curl "https://api.paste.ee/v1/syntaxes/<id>"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
   "syntax":{
     "id": "1",
     "short": "text",
     "name": "Text"
   },
   "success":true
}

This endpoint returns information about a syntax.

HTTP Request

GET https://api.paste.ee/v1/syntaxes/<id>

Users

User/key information

curl "https://api.paste.ee/v1/users/info"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
  "type":"UserApplication"
}

This endpoint will return information about the current api key.

HTTP Request

GET https://api.paste.ee/v1/users/info

User Authentication

curl "https://api.paste.ee/v1/users/authenticate"
  -H "X-Auth-Token: meowmeowmeow"

The above command returns JSON structured like this:

{
  "success": true,
  "key": "<new or existing user application key>"
}

This endpoint authenticates users for UserApplications, allowing further api functionality like listing pastes and submitting them while attaching them to the user's account.

You can also use the url https://paste.ee/account/api/authorize/<application key> to have the user generate a token themselves.

HTTP Request

POST https://api.paste.ee/v1/users/authenticate

Request Body

Parameter	Description
username	The user's username.
password	The user's password.

Errors

The Paste.ee API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request sucks
401	Unauthorized -- Your Application/User application key is wrong.
403	Forbidden -- The application is a standard Application, and the resource requires a UserApplication.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
406	Not Acceptable -- You requested a format that isn't json or xml.
429	Too Many Requests -- You're submitting pastes too fast, slow down and try again later.
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarially offline for maintanance. Please try again later.