PasteFox API Reference

Complete reference for the PasteFox REST API. Create, manage, and share code snippets programmatically.

v1 — stablehttps://api.pastefox.com/v1

v2 — cursor paginationhttps://api.pastefox.com/v2

Authentication

Include your API key in every authenticated request via one of these headers:

Header (recommended)

X-API-Key: pk_your_api_key_here

Bearer token

Authorization: Bearer pk_your_api_key_here

Anonymous Paste Creation

You can create pastes without an API key, but they are forced PUBLIC, expire in max 7 days, and cannot be edited or deleted.

Get your API key: Dashboard → API Keys

Rate Limiting

Global

200 / 60s

Paste create

30 / 10min

Paste read

120 / min

Response headers on 429 Too Many Requests:

X-RateLimit-RemainingRemaining requests in current window

X-RateLimit-ResetISO 8601 timestamp when window resets

Retry-AfterSeconds until you can retry

Repeated violations will auto-revoke your API key.

Response Format

Success (v1)

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "content", "message": "Required" }
  ]
}

Pastes

POST/pastesoptional

Create a paste

Works with or without an API key. Anonymous pastes are forced PUBLIC and expire in max 7 days.

Request body

contentrequired

string

Paste content (required, min 1 char)

title

string · default: Untitled paste

Paste title

language

string

Language for syntax highlighting (auto-detected if omitted)

visibility

enum · default: PUBLIC

PUBLIC, PRIVATE, or UNLISTED

password

string

Password-protect the paste (4–100 chars)

expiresAt

ISO 8601

Expiration date. Anonymous: max 7 days

maxViews

integer

Auto-delete after N views (min 1)

isOneTimeView

boolean · default: false

Delete after first view

effect

enum · default: NONE

Visual reveal effect

folderId

string

Place in a folder (requires API key)

Example

curl -X POST "https://api.pastefox.com/v1/pastes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_your_key" \
  -d '{"content": "Hello!", "title": "My Paste", "visibility": "PUBLIC"}'

201 — Created

{
  "success": true,
  "data": {
    "slug": "abc123",
    "title": "My Paste",
    "visibility": "PUBLIC",
    "viewCount": 0,
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}

400 — Validation error

401 — Auth required (when using folderId)

GET/pasteskey required

List your pastes

Returns a paginated list of your own pastes.

Query parameters

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–100)

search

string

Search in title and content

visibility

enum

Filter by PUBLIC, PRIVATE, or UNLISTED

language

string

Filter by language

folderId

string

Filter by folder

sortBy

string · default: createdAt

createdAt, viewCount, title, updatedAt

sortOrder

enum · default: desc

asc or desc

200 — Paginated list

{
  "success": true,
  "data": {
    "items": [...],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

GET/pastes/{slug}optional

Get paste by slug

Public/unlisted pastes readable without auth. Private pastes require the owner's API key. Password-protected pastes return 423 with partial data.

slugrequired

string

Paste slug (from URL)

200 — Paste data

403 — Private paste — not your paste

404 — Not found or deleted

410 — Expired or max views reached

423 — Password required

{
  "success": true,
  "data": {
    "slug": "abc123",
    "title": "Secret",
    "hasPassword": true,
    "content": null
  }
}

PATCH/pastes/{slug}key required

Update a paste

Only the owner can update. Send only the fields you want to change.

title

string

New title (max 100 chars)

content

string

New content (min 1 char)

language

string

New language

visibility

enum

PUBLIC, PRIVATE, or UNLISTED

password

string | null

Set password (4–100 chars) or null to remove

expiresAt

ISO 8601 | null

Set or remove expiration

maxViews

integer | null

Set or remove max views

effect

enum

Change visual effect

allowClone

boolean

Allow other users to clone

200 — Updated paste

403 — Not your paste

404 — Not found

DELETE/pastes/{slug}key required

Delete a paste

Soft-deletes the paste. Only the owner can delete.

200 — Deleted

{
  "success": true,
  "data": { "slug": "abc123", "deleted": true }
}

403 — Not your paste

404 — Not found

GET/pastes/{slug}/rawoptional

Get raw content

Returns the paste content as plain text (text/plain). Same access rules as GET /pastes/{slug}.

200 — Raw text content

403 — Private paste

423 — Password required

POST/pastes/{slug}/verifypublic

Verify paste password

Submit the password to unlock a password-protected paste. Returns full paste data on success.

passwordrequired

string

The paste password

Example

curl -X POST "https://api.pastefox.com/v1/pastes/abc123/verify" \
  -H "Content-Type: application/json" \
  -d '{"password": "mysecret"}'

200 — Password correct — full paste data

400 — Password field missing

401 — Wrong password

404 — Not found or no password set

POST/pastes/{slug}/clonekey required

Clone a paste

Creates a copy of the paste under your account. Cannot clone private pastes from other users or pastes with cloning disabled.

201 — Cloned paste

403 — Cloning not allowed or private paste

POST/pastes/{slug}/likekey required

Like or dislike a paste

Toggle like/dislike. Calling again with the same value removes it.

isDislike

boolean · default: false

Set to true for dislike

200 — Action result

{
  "success": true,
  "data": { "action": "liked" }
}

Folders

GET/folderskey required

List your folders

Returns all folders with paste and children counts, ordered by sortOrder.

200 — Folder list

{
  "success": true,
  "data": [
    {
      "id": "clx...",
      "name": "JavaScript",
      "slug": "javascript-a1b2",
      "visibility": "PRIVATE",
      "_count": { "pastes": 12, "children": 2 }
    }
  ]
}

POST/folderskey required

Create a folder

Max 50 folders per user.

namerequired

string

Folder name (1–100 chars)

description

string

Description (max 500 chars)

color

string

Color code (max 20 chars)

icon

string

Icon name (max 50 chars)

visibility

enum · default: PRIVATE

PUBLIC or PRIVATE

parentId

string

Parent folder ID for nesting

201 — Folder created

400 — Validation error

403 — Folder limit reached (max 50)

GET/folders/{id}key required

Get folder with pastes

Returns the folder details including its pastes and children count.

idrequired

string

Folder ID

200 — Folder with pastes

404 — Not found

PUT/folders/{id}key required

Update a folder

Only send the fields you want to change.

name

string

New name (1–100 chars)

description

string | null

New description

color

string | null

New color

icon

string | null

New icon

visibility

enum

PUBLIC or PRIVATE

200 — Updated

404 — Not found

DELETE/folders/{id}key required

Delete a folder

Permanently deletes the folder. Pastes inside are not deleted, they become unfoldered.

idrequired

string

Folder ID

200 — Deleted

404 — Not found

Explore & Public Endpoints

GET/explorepublic

Browse public pastes

Returns paginated public pastes. Only shows pastes without passwords.

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–50)

sort

enum · default: newest

newest, oldest, or popular

language

string

Filter by language

search

string

Search in title

200 — Public paste list

GET/users/public/{username}public

Get public user profile

Returns public profile info. Only works for users with public profiles enabled.

usernamerequired

string

Username

200 — Public profile

{
  "success": true,
  "data": {
    "username": "johndoe",
    "name": "John",
    "bio": "Developer",
    "profileViews": 142,
    "_count": { "pastes": 28 }
  }
}

404 — Not found or profile is private

GET/users/public/{username}/pastespublic

Get user's public pastes

Paginated list of a user's public pastes.

usernamerequired

string

Username

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–50)

200 — Public paste list

404 — Profile not found

GET/healthpublic

Health check

200 — Healthy

{
  "status": "healthy",
  "timestamp": "2026-04-03T12:00:00.000Z"
}

503 — Unhealthy (database down)

GET/statspublic

Platform statistics

200 — Stats

{
  "success": true,
  "data": {
    "totalPastes": 15420,
    "totalUsers": 3200,
    "totalViews": 892000,
    "languages": 130
  }
}

Users

GET/users/mekey required

Get your own profile

Returns your full profile including paste, folder, and API key counts.

200 — Your profile

{
  "success": true,
  "data": {
    "id": "clx...",
    "email": "[email protected]",
    "username": "yourname",
    "role": "USER",
    "emailVerified": true,
    "_count": { "pastes": 42, "folders": 5, "apiKeys": 2 }
  }
}

Paste Effects

Set via the effect field when creating or updating a paste.

NONESCRATCHMATRIXGLITCHCONFETTIPUZZLESLOTSSHAKEPASSWORDFIREWORKSTYPEWRITERBLUR

V2 API Differences

V2 uses the same paths under /api/v2 with these changes:

Response envelope

{ data, meta, error } instead of { success, data, error }

Cursor pagination

Use cursor param for efficient paging. Response includes nextCursor in meta.

Search param

Use q instead of search

Sort param

Use sort with - prefix for desc, e.g. -createdAt (replaces sortBy + sortOrder)

Burn after read

burnAfterRead replaces isOneTimeView

Password paste

423 returns error hint only, no partial data

V2 list response example

{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "hasMore": true,
    "nextCursor": "clx..."
  }
}

PasteFox API Reference

Complete reference for the PasteFox REST API. Create, manage, and share code snippets programmatically.

v1 — stablehttps://api.pastefox.com/v1

v2 — cursor paginationhttps://api.pastefox.com/v2

Authentication

Include your API key in every authenticated request via one of these headers:

Header (recommended)

X-API-Key: pk_your_api_key_here

Bearer token

Authorization: Bearer pk_your_api_key_here

Anonymous Paste Creation

You can create pastes without an API key, but they are forced PUBLIC, expire in max 7 days, and cannot be edited or deleted.

Get your API key: Dashboard → API Keys

Rate Limiting

Global

200 / 60s

Paste create

30 / 10min

Paste read

120 / min

Response headers on 429 Too Many Requests:

X-RateLimit-RemainingRemaining requests in current window

X-RateLimit-ResetISO 8601 timestamp when window resets

Retry-AfterSeconds until you can retry

Repeated violations will auto-revoke your API key.

Response Format

Success (v1)

{
  "success": true,
  "data": { ... }
}

Error

{
  "success": false,
  "error": "Validation failed",
  "details": [
    { "field": "content", "message": "Required" }
  ]
}

Pastes

POST/pastesoptional

Create a paste

Works with or without an API key. Anonymous pastes are forced PUBLIC and expire in max 7 days.

Request body

contentrequired

string

Paste content (required, min 1 char)

title

string · default: Untitled paste

Paste title

language

string

Language for syntax highlighting (auto-detected if omitted)

visibility

enum · default: PUBLIC

PUBLIC, PRIVATE, or UNLISTED

password

string

Password-protect the paste (4–100 chars)

expiresAt

ISO 8601

Expiration date. Anonymous: max 7 days

maxViews

integer

Auto-delete after N views (min 1)

isOneTimeView

boolean · default: false

Delete after first view

effect

enum · default: NONE

Visual reveal effect

folderId

string

Place in a folder (requires API key)

Example

curl -X POST "https://api.pastefox.com/v1/pastes" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: pk_your_key" \
  -d '{"content": "Hello!", "title": "My Paste", "visibility": "PUBLIC"}'

201 — Created

{
  "success": true,
  "data": {
    "slug": "abc123",
    "title": "My Paste",
    "visibility": "PUBLIC",
    "viewCount": 0,
    "createdAt": "2026-04-03T12:00:00.000Z"
  }
}

400 — Validation error

401 — Auth required (when using folderId)

GET/pasteskey required

List your pastes

Returns a paginated list of your own pastes.

Query parameters

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–100)

search

string

Search in title and content

visibility

enum

Filter by PUBLIC, PRIVATE, or UNLISTED

language

string

Filter by language

folderId

string

Filter by folder

sortBy

string · default: createdAt

createdAt, viewCount, title, updatedAt

sortOrder

enum · default: desc

asc or desc

200 — Paginated list

{
  "success": true,
  "data": {
    "items": [...],
    "total": 42,
    "page": 1,
    "limit": 20,
    "totalPages": 3
  }
}

GET/pastes/{slug}optional

Get paste by slug

Public/unlisted pastes readable without auth. Private pastes require the owner's API key. Password-protected pastes return 423 with partial data.

slugrequired

string

Paste slug (from URL)

200 — Paste data

403 — Private paste — not your paste

404 — Not found or deleted

410 — Expired or max views reached

423 — Password required

{
  "success": true,
  "data": {
    "slug": "abc123",
    "title": "Secret",
    "hasPassword": true,
    "content": null
  }
}

PATCH/pastes/{slug}key required

Update a paste

Only the owner can update. Send only the fields you want to change.

title

string

New title (max 100 chars)

content

string

New content (min 1 char)

language

string

New language

visibility

enum

PUBLIC, PRIVATE, or UNLISTED

password

string | null

Set password (4–100 chars) or null to remove

expiresAt

ISO 8601 | null

Set or remove expiration

maxViews

integer | null

Set or remove max views

effect

enum

Change visual effect

allowClone

boolean

Allow other users to clone

200 — Updated paste

403 — Not your paste

404 — Not found

DELETE/pastes/{slug}key required

Delete a paste

Soft-deletes the paste. Only the owner can delete.

200 — Deleted

{
  "success": true,
  "data": { "slug": "abc123", "deleted": true }
}

403 — Not your paste

404 — Not found

GET/pastes/{slug}/rawoptional

Get raw content

Returns the paste content as plain text (text/plain). Same access rules as GET /pastes/{slug}.

200 — Raw text content

403 — Private paste

423 — Password required

POST/pastes/{slug}/verifypublic

Verify paste password

Submit the password to unlock a password-protected paste. Returns full paste data on success.

passwordrequired

string

The paste password

Example

curl -X POST "https://api.pastefox.com/v1/pastes/abc123/verify" \
  -H "Content-Type: application/json" \
  -d '{"password": "mysecret"}'

200 — Password correct — full paste data

400 — Password field missing

401 — Wrong password

404 — Not found or no password set

POST/pastes/{slug}/clonekey required

Clone a paste

Creates a copy of the paste under your account. Cannot clone private pastes from other users or pastes with cloning disabled.

201 — Cloned paste

403 — Cloning not allowed or private paste

POST/pastes/{slug}/likekey required

Like or dislike a paste

Toggle like/dislike. Calling again with the same value removes it.

isDislike

boolean · default: false

Set to true for dislike

200 — Action result

{
  "success": true,
  "data": { "action": "liked" }
}

Folders

GET/folderskey required

List your folders

Returns all folders with paste and children counts, ordered by sortOrder.

200 — Folder list

{
  "success": true,
  "data": [
    {
      "id": "clx...",
      "name": "JavaScript",
      "slug": "javascript-a1b2",
      "visibility": "PRIVATE",
      "_count": { "pastes": 12, "children": 2 }
    }
  ]
}

POST/folderskey required

Create a folder

Max 50 folders per user.

namerequired

string

Folder name (1–100 chars)

description

string

Description (max 500 chars)

color

string

Color code (max 20 chars)

icon

string

Icon name (max 50 chars)

visibility

enum · default: PRIVATE

PUBLIC or PRIVATE

parentId

string

Parent folder ID for nesting

201 — Folder created

400 — Validation error

403 — Folder limit reached (max 50)

GET/folders/{id}key required

Get folder with pastes

Returns the folder details including its pastes and children count.

idrequired

string

Folder ID

200 — Folder with pastes

404 — Not found

PUT/folders/{id}key required

Update a folder

Only send the fields you want to change.

name

string

New name (1–100 chars)

description

string | null

New description

color

string | null

New color

icon

string | null

New icon

visibility

enum

PUBLIC or PRIVATE

200 — Updated

404 — Not found

DELETE/folders/{id}key required

Delete a folder

Permanently deletes the folder. Pastes inside are not deleted, they become unfoldered.

idrequired

string

Folder ID

200 — Deleted

404 — Not found

Explore & Public Endpoints

GET/explorepublic

Browse public pastes

Returns paginated public pastes. Only shows pastes without passwords.

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–50)

sort

enum · default: newest

newest, oldest, or popular

language

string

Filter by language

search

string

Search in title

200 — Public paste list

GET/users/public/{username}public

Get public user profile

Returns public profile info. Only works for users with public profiles enabled.

usernamerequired

string

Username

200 — Public profile

{
  "success": true,
  "data": {
    "username": "johndoe",
    "name": "John",
    "bio": "Developer",
    "profileViews": 142,
    "_count": { "pastes": 28 }
  }
}

404 — Not found or profile is private

GET/users/public/{username}/pastespublic

Get user's public pastes

Paginated list of a user's public pastes.

usernamerequired

string

Username

page

integer · default: 1

Page number

limit

integer · default: 20

Items per page (1–50)

200 — Public paste list

404 — Profile not found

GET/healthpublic

Health check

200 — Healthy

{
  "status": "healthy",
  "timestamp": "2026-04-03T12:00:00.000Z"
}

503 — Unhealthy (database down)

GET/statspublic

Platform statistics

200 — Stats

{
  "success": true,
  "data": {
    "totalPastes": 15420,
    "totalUsers": 3200,
    "totalViews": 892000,
    "languages": 130
  }
}

Users

GET/users/mekey required

Get your own profile

Returns your full profile including paste, folder, and API key counts.

200 — Your profile

{
  "success": true,
  "data": {
    "id": "clx...",
    "email": "[email protected]",
    "username": "yourname",
    "role": "USER",
    "emailVerified": true,
    "_count": { "pastes": 42, "folders": 5, "apiKeys": 2 }
  }
}

Paste Effects

Set via the effect field when creating or updating a paste.

NONESCRATCHMATRIXGLITCHCONFETTIPUZZLESLOTSSHAKEPASSWORDFIREWORKSTYPEWRITERBLUR

V2 API Differences

V2 uses the same paths under /api/v2 with these changes:

Response envelope

{ data, meta, error } instead of { success, data, error }

Cursor pagination

Use cursor param for efficient paging. Response includes nextCursor in meta.

Search param

Use q instead of search

Sort param

Use sort with - prefix for desc, e.g. -createdAt (replaces sortBy + sortOrder)

Burn after read

burnAfterRead replaces isOneTimeView

Password paste

423 returns error hint only, no partial data

V2 list response example

{
  "data": [...],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20,
    "hasMore": true,
    "nextCursor": "clx..."
  }
}