Create a paste

POST a paste to paste.hep.gg with a bearer API key. Request body, JSON envelope, and error codes.

Create a paste over HTTP. This is the endpoint behind the CLI, ShareX, and any script you write. Authenticate with a bearer API key minted at dashboard/snippets/keys.

Authentication#

Send your key as a bearer token:

Authorization: Bearer hepgg_pst_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

The key resolves to your account, so the paste is attributed to you and counts against your plan's size cap and (for Free accounts) total paste count. A disabled or unknown key returns 401.

Request body#

Content type is application/json.

Response#

A 200 with the standard JSON envelope.

{
  "ok": true,
  "data": {
    "id": "aB3dE6kp",
    "url": "https://paste.hep.gg/aB3dE6kp",
    "expiresAt": "2026-08-27T00:00:00.000Z",
    "anonymous": false
  }
}

Examples#

curl https://paste.hep.gg/api/paste \
  -H "Authorization: Bearer hepgg_pst_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "deploy log",
    "content": "==> building\n==> done in 4.2s",
    "language": "bash",
    "visibility": "unlisted"
  }'

const res = await fetch("https://paste.hep.gg/api/paste", {
  method: "POST",
  headers: {
    Authorization: "Bearer hepgg_pst_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "deploy log",
    content: "==> building\n==> done in 4.2s",
    language: "bash",
    visibility: "unlisted",
  }),
});
 
const json = await res.json();
if (!json.ok) throw new Error(json.error);
console.log(json.data.url);

Pipe a file straight in from the shell:

jq -Rs '{content: ., language: "python"}' main.py | \
  curl https://paste.hep.gg/api/paste \
    -H "Authorization: Bearer hepgg_pst_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    --data-binary @-

Visibility#

The default on paste.hep.gg/api/paste is public. (The dashboard's own /api/v1/snippets create path defaults to unlisted instead, so set visibility explicitly if you care.)

Language detection#

If you omit language, the server runs auto-detection on the content. To keep the rendered page honest, detection only applies when:

• the content has at least 20 non-whitespace characters, and
• the detector is confident, and
• the detected language is one of a curated common set (JavaScript, TypeScript, Python, Go, Rust, Java, C/C++, C#, Kotlin, Swift, Ruby, PHP, Bash, PowerShell, HTML, CSS, SCSS, JSON, YAML, XML, Markdown, SQL, GraphQL, Dockerfile, diff, Lua, Scala).

Short or ambiguous blobs stay plaintext. Pass language explicitly when you already know it, especially for languages outside that set.

Errors#

Errors use { "ok": false, "error": "...", "code"?: "..." } with a matching HTTP status.

{
  "ok": false,
  "error": "Paste too large. Max 1 MB."
}

{
  "ok": false,
  "error": "You've reached your snippet limit. Delete a few or upgrade to Prime.",
  "code": "PASTE_TOTAL_CAP"
}