API Reference

Snip provides a full REST API for programmatic access. All endpoints return JSON.

Base URL

url

http://localhost:53524/api/v1

Endpoints

Method	Path	Auth	Description
POST	`/api/v1/pastes`	-	Create a paste
GET	`/api/v1/pastes`	-	List pastes
GET	`/api/v1/pastes/{slug}`	-	Get a paste
DELETE	`/api/v1/pastes/{slug}`	Token	Delete a paste
GET	`/api/v1/pastes/{slug}/raw`	-	Raw content
GET	`/api/v1/search?q=`	-	Search pastes
GET	`/api/v1/stats`	-	Get statistics
GET	`/healthz`	-	Health check
GET	`/metrics`	-	Prometheus metrics
GET	`/version`	-	Version info
POST	`/api/v1/tokens`	Token	Create API token
DELETE	`/api/v1/tokens/{id}`	Token	Revoke API token
POST	`/api/v1/backup`	Token	Database backup

Create a Paste

bash

curl -X POST http://localhost:53524/api/v1/pastes \
  -H "Content-Type: application/json" \
  -d '{
    "content": "package main\n\nimport \"fmt\"\n\nfunc main() {\n\tfmt.Println(\"Hello, World!\")\n}",
    "language": "go",
    "title": "Hello World",
    "expires_in": "1d"
  }'

Request Body

Field	Type	Default	Description
`content`	string	required	Paste content
`title`	string	`""`	Paste title
`language`	string	`"auto"`	Language for syntax highlighting
`password`	string	`""`	Password protection
`expires_in`	string	`"never"`	Expiration: 10m, 1h, 1d, 1w, 1m
`burn_after_read`	bool	`false`	Delete after first view
`max_views`	int	`0`	Max views (0 = unlimited)
`custom_slug`	string	`""`	Custom URL slug

Response

json

{
  "slug": "a1b2c3d4",
  "title": "Hello World",
  "content": "package main\n\nimport \"fmt\"\n\nfunc main() {\n\tfmt.Println(\"Hello, World!\")\n}",
  "language": "go",
  "file_size": 75,
  "views": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "url": "http://localhost:53524/a1b2c3d4",
  "raw_url": "http://localhost:53524/a1b2c3d4/raw"
}

Get a Paste

bash

curl http://localhost:53524/api/v1/pastes/a1b2c3d4

# With password
curl "http://localhost:53524/api/v1/pastes/a1b2c3d4?password=mypassword"

List Pastes

bash

curl http://localhost:53524/api/v1/pastes?limit=20&offset=0

Delete a Paste

Requires API token authentication.

bash

curl -X DELETE http://localhost:53524/api/v1/pastes/a1b2c3d4 \
  -H "Authorization: snip_your_api_token"

Search

bash

curl "http://localhost:53524/api/v1/search?q=hello"

Statistics

bash

curl http://localhost:53524/api/v1/stats

json

{
  "total_pastes": 42,
  "total_views": 1337,
  "total_tokens": 3,
  "total_bytes": 524288
}

Health Check

bash

curl http://localhost:53524/healthz

json

{
  "status": "ok",
  "time": "2024-01-15T10:30:00Z",
  "version": "v1.0.0",
  "pastes": 42,
  "views": 1337,
  "tokens": 3,
  "storage": 524288
}

Prometheus Metrics

bash

curl http://localhost:53524/metrics

prometheus

# HELP snip_pastes_total Total number of pastes
# TYPE snip_pastes_total gauge
snip_pastes_total 42
# HELP snip_views_total Total view count
# TYPE snip_views_total counter
snip_views_total 1337
# HELP snip_tokens_total Total API tokens
# TYPE snip_tokens_total gauge
snip_tokens_total 3
# HELP snip_storage_bytes Total storage used
# TYPE snip_storage_bytes gauge
snip_storage_bytes 524288

Authentication

Generate an API token from the Settings page, then include it in the Authorization header:

bash

curl -H "Authorization: snip_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  http://localhost:53524/api/v1/pastes

File Upload

bash

curl -X POST http://localhost:53524/api/v1/pastes \
  -H "Authorization: snip_your_token" \
  -F "file=@main.go" \
  -F "language=go" \
  -F "title=My Go file"

Database Backup

bash

curl -X POST http://localhost:53524/api/v1/backup \
  -H "Authorization: snip_your_token"