REST API Reference

SnipShare exposes a complete REST API under the snipshare/v1 namespace. All endpoints are accessible at /wp-json/snipshare/v1/.

---

Authentication

Method	Use Case
WP Cookie + X-WP-Nonce header	Logged-in users on the frontend. Get nonce via wp_rest_nonce() or wpApiSettings.nonce.
Application Passwords	External apps, mobile clients, CLI tools. Create at WP Admin → Users → Edit User → Application Passwords.

Public endpoints (reading public pastes, tags, oEmbed) require no authentication.

---

Global Parameters

All list endpoints support these query parameters:

Parameter	Description
page	Page number (default: 1)
per_page	Results per page (default: 10, max: 100)
orderby	Sort field (e.g., created_at, star_count, view_count)
order	asc or desc (default: desc)
_fields	Comma-separated list of fields to include in response (sparse fieldsets)
_embed	Include linked resources inline (author, files)

Pagination response headers: X-WP-Total (total items), X-WP-TotalPages (total pages).

---

Pastes

List Pastes

GET /wp-json/snipshare/v1/pastes

Returns public pastes. Supports additional filter params:

Param	Description
language	Filter by language slug
user	Filter by WP user ID or username
tag	Filter by tag slug
search	Full-text search on title and description
status	active (default)

Create Paste

POST /wp-json/snipshare/v1/pastes

Auth required. Request body (JSON):

{
  "title": "My helper",
  "description": "Useful PHP utility",
  "visibility": "public",
  "expiration": "never",
  "password": "",
  "burn_after_read": false,
  "tags": ["php", "utilities"],
  "files": [
    {
      "filename": "helper.php",
      "content": "<?php function foo() {}",
      "language": "php"
    }
  ]
}

Get Paste

GET /wp-json/snipshare/v1/pastes/{id}

Public for public/unlisted pastes. Requires auth for private pastes (owner only).

Update Paste

PUT /wp-json/snipshare/v1/pastes/{id}

Owner or moderator only. Same body shape as create. Each changed file generates a revision.

Delete Paste (Trash)

DELETE /wp-json/snipshare/v1/pastes/{id}

Owner or moderator only. Sets status to trashed.

Fork Paste

POST /wp-json/snipshare/v1/pastes/{id}/fork

Auth required. Clones all files into a new paste. Returns the new paste object.

Toggle Star

POST /wp-json/snipshare/v1/pastes/{id}/star

Auth required. Toggles star on/off. Response: { "starred": bool, "star_count": int }.

Report Paste

POST /wp-json/snipshare/v1/pastes/{id}/report

Auth required. Body: { "reason": "spam|inappropriate|malicious|copyright|other", "details": "optional text" }.

Unlock Password-Protected Paste

POST /wp-json/snipshare/v1/pastes/{id}/unlock

Body: { "password": "secret" }. Stores unlock in session. Returns 200 on success, 403 on wrong password.

List Revisions

GET /wp-json/snipshare/v1/pastes/{id}/revisions

Owner/moderator for private pastes, public for public/unlisted.

Get Diff

GET /wp-json/snipshare/v1/pastes/{id}/diff?from=1&to=3

Returns structured diff data per file.

Raw Content

GET /wp-json/snipshare/v1/pastes/{id}/raw
GET /wp-json/snipshare/v1/pastes/{id}/raw/{file_id}

Returns plain text. The /raw/{file_id} variant returns a single file’s content.

Download

GET /wp-json/snipshare/v1/pastes/{id}/download

Returns single file or ZIP archive download.

---

Files

Add File to Paste

POST /wp-json/snipshare/v1/pastes/{id}/files

Owner only. Body: { "filename": "...", "content": "...", "language": "..." }.

Update File

PUT /wp-json/snipshare/v1/pastes/{id}/files/{fid}

Owner only. Body: any subset of filename, content, language.

Delete File

DELETE /wp-json/snipshare/v1/pastes/{id}/files/{fid}

Owner only. Paste must retain at least one file.

---

Collections

List My Collections

GET /wp-json/snipshare/v1/collections

Auth required. Returns the current user’s collections.

Create Collection

POST /wp-json/snipshare/v1/collections

Body: { "name": "...", "slug": "...", "description": "...", "visibility": "public|private" }.

Get Collection

GET /wp-json/snipshare/v1/collections/{id}

Owner for private, public for public collections.

Update Collection

PUT /wp-json/snipshare/v1/collections/{id}

Owner only. Updatable fields: name, description, visibility.

Delete Collection

DELETE /wp-json/snipshare/v1/collections/{id}

Owner only. Pastes are not affected.

Add Paste to Collection

POST /wp-json/snipshare/v1/collections/{id}/pastes

Body: { "paste_id": 42 }.

Remove Paste from Collection

DELETE /wp-json/snipshare/v1/collections/{id}/pastes/{paste_id}

---

Tags

List All Tags

GET /wp-json/snipshare/v1/tags

Public. Returns tags sorted by count descending.

List Pastes by Tag

GET /wp-json/snipshare/v1/tags/{slug}/pastes

Public. Returns public pastes with this tag. Supports global list params.

---

Admin Endpoints

Require the snipshare/moderate ability.

List Reports

GET /wp-json/snipshare/v1/admin/reports?status=pending

Filter by status: pending, reviewed, dismissed.

Review Report

PUT /wp-json/snipshare/v1/admin/reports/{id}

Body: { "status": "reviewed|dismissed", "trash_paste": false }.

Force Paste Status

PUT /wp-json/snipshare/v1/admin/pastes/{id}/status

Body: { "status": "active|trashed|expired" }.

---

Embed

Get Embed Data

GET /wp-json/snipshare/v1/embed/{hash}

Public. Returns lightweight paste data for embedding. Private pastes return 404.

---

Error Responses

All errors follow the standard WP REST error format:

{
  "code": "rest_forbidden",
  "message": "You do not have permission to do that.",
  "data": { "status": 403 }
}

Common error codes: rest_forbidden (403), rest_not_found (404), rest_invalid_param (400), snipshare_rate_limit_exceeded (429).