Developer API V 1

PasterLink API Reference

This is the official PasterLink REST API for creators. Automate paste publishing, read analytics, query earnings, and fetch your profile - all with a Bearer token. See the full PasterLink feature set for what the API can automate, or start with the API overview. Building a bot? See the Telegram bot workflow.

Bulk Upload (Python)

Download a ready-to-run Python uploader that creates pastes from TXT or CSV files.

Download ZIP

Authentication

Every request must include a Bearer token in the Authorization header. Tokens are available in Creator Dashboard → API Keys and are creator-only.

Authorization: Bearer YOUR_API_KEY

Tokens are hashed server-side — the plaintext is shown once at creation.
A revoked or expired token returns 401.
A key whose account is not a Creator Mode account returns 403 with the FORBIDDEN JSON error envelope. Every /api/v1 request gets this JSON response, with or without an Accept header.
Send Accept: application/json on every request. Without it, a 429 response is an HTML page instead of JSON.

Base URL

https://pasterlink.com/api/v1

All endpoints below are relative to this base URL.

Versioning & Deprecation

Versions are encoded in the URL path (/api/v1/, /api/v2/, …). Every response from a versioned endpoint includes an X-API-Version header so you can detect version mismatches:

X-API-Version: 1

Deprecation — when a version is scheduled for removal, two additional headers appear on every response for that version:

Sunset: Sun, 01 Jan 2028 00:00:00 GMT
Deprecation: true

Deprecated versions are maintained for a minimum of 12 months after the sunset date is first announced.
We will notify creators via the dashboard before any version is removed.
v1 is currently the only stable version. The Sunset header will not appear until deprecation is officially announced.

Error Envelope

All error responses follow a consistent JSON envelope so you can handle them uniformly.

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "The body field is required.",
    "details": {
      "body": ["The body field is required."]
    }
  }
}

The details key is only present on 422 responses. Common code values: UNAUTHORIZED, FORBIDDEN, NOT_FOUND, VALIDATION_FAILED, IDEMPOTENCY_KEY_REUSED and ACCOUNT_PENDING_DELETION (403, for an account scheduled for deletion).

Rate Limits

All /api/v1/ routes share one limit of 60 requests per minute for each API key. The count is kept per key, not per IP address. Successful responses carry X-RateLimit-Limit and X-RateLimit-Remaining headers.

Exceeding the limit returns 429 Too Many Requests with a Retry-After header in seconds. Wait that long before you retry. The 429 body is the framework default (a JSON message when you send Accept: application/json, an HTML page otherwise), not the error envelope, so rely on the status code and the Retry-After header.

Pastes

List Pastes

GET/pastes

Returns a paginated list of all pastes belonging to the authenticated creator.

Query parameters

Param	Type	Description
page	integer	Page number (default: 1, 25 per page)

Response 200

{
  "data": [
    {
      "id": 1,
      "slug": "aB93kL",
      "title": "My Paste",
      "status": "active",
      "as_button": false,
      "seen_nbr": 42,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "updated_at": "2024-01-01T00:00:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "last_page": 3,
    "per_page": 25,
    "total": 72
  }
}

Create Paste

POST/pastes

Creates a new paste and returns the full paste object.

Request body (application/json)

Field	Type	Required	Description
body	string	Yes	Paste content (max 500 000 chars)
title	string	No	Optional title (max 255 chars)
password	string	No	Password-protect the paste
as_button	boolean	No	Display as a button link (default: false)

Example

curl -X POST https://pasterlink.com/api/v1/pastes \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"body":"Hello from API","title":"My first paste"}'

Response 201

{
  "id": 1,
  "slug": "aB93kL",
  "url": "https://pasterlink.com/paste/aB93kL",
  "title": "My first paste",
  "body": "<p>Hello from API</p>",
  "as_button": false,
  "status": null,
  "seen_nbr": 0,
  "password_protected": false,
  "created_at": "2024-01-01T00:00:00+00:00",
  "updated_at": "2024-01-01T00:00:00+00:00"
}

body is returned as HTML. Plain text you send is wrapped in paragraph markup when it is saved, so Hello from API comes back as <p>Hello from API</p>. HTML you send is kept as HTML after sanitizing.
status is null in the create response only. Get, update and list return the real status, which is "active" for a new paste.
The 500,000-character limit applies to the body you submit, before it is formatted and sanitized. It is not a limit on the size of the stored HTML.
The paste address is generated. A slug field on create is ignored.

Idempotency (optional)

Send an Idempotency-Key header with any unique string to make a create request safe to retry. It is supported on this endpoint only, and keys are scoped to your account.

Repeating the same key with the same request payload within 60 seconds of the first successful request creates nothing new. You get the original status and body back, plus an Idempotency-Replay: true header.
Repeating the same key with a different payload returns 409 with the error code IDEMPOTENCY_KEY_REUSED.
Only successful (2xx) responses are remembered, so a failed request can be retried with the same key. After 60 seconds the key is forgotten and the same request creates a new paste.
A key is remembered once the first request has finished. Two identical requests sent at the same moment are not de-duplicated.

Get Paste

GET/pastes/{slug}

Returns a single paste by slug. Returns 404 if the paste does not exist or belongs to another account.

Example

curl https://pasterlink.com/api/v1/pastes/aB93kL \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{
  "id": 1,
  "slug": "aB93kL",
  "url": "https://pasterlink.com/paste/aB93kL",
  "title": "My first paste",
  "body": "<p>Hello from API</p>",
  "as_button": false,
  "status": "active",
  "seen_nbr": 17,
  "password_protected": false,
  "created_at": "2024-01-01T00:00:00+00:00",
  "updated_at": "2024-01-01T00:00:00+00:00"
}

Update Paste

PATCH/pastes/{slug}

Partially updates a paste. Only include the fields you want to change. Send "password": null to remove an existing password. slug, status, password_code and body_tier1 cannot be set and return 422. Returns 404 if the slug does not exist and 403 if the paste belongs to another account.

Request body

Field	Type	Description
title	string \| null	New title
body	string	New paste content (max 500 000 chars). Omit the field to keep the current content.
password	string \| null	Set or remove password (`null` removes it)
as_button	boolean \| null	Toggle button display mode

Example

curl -X PATCH https://pasterlink.com/api/v1/pastes/aB93kL \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Updated title","password":null}'

Response 200

Returns the full updated paste object (same shape as Create/Get).

Delete Paste

DELETE/pastes/{slug}

Permanently deletes a paste. This action cannot be undone. Returns 404 if the slug does not exist and 403 if the paste belongs to another account.

Example

curl -X DELETE https://pasterlink.com/api/v1/pastes/aB93kL \
  -H "Authorization: Bearer YOUR_API_KEY"

Response 200

{ "message": "Paste deleted." }

Other Endpoints

Analytics

GET/analytics

Returns aggregated view analytics for all pastes owned by the authenticated creator.

Query parameters

Param	Values	Description
period	`7days` · `30days` · `6months`	Date window (default: `7days`)

Response 200

{
  "period": "7days",
  "dateRange": { "start": "2024-01-01", "end": "2024-01-07" },
  "totals": {
    "views": 1240,
    "unique_visitors": 875
  },
  "daily": [
    { "date": "2024-01-01", "views": 180, "unique_visitors": 130 },
    ...
  ],
  "countries": [
    { "country": "United States", "country_code": "US", "views": 400 },
    ...
  ],
  "devices": [
    { "device": "Desktop", "views": 820 },
    { "device": "Mobile",  "views": 420 }
  ],
  "referrers": [
    { "referrer": "Direct / none", "views": 600 },
    { "referrer": "google.com",    "views": 240 },
    ...
  ]
}

Earnings

GET/earnings

Returns a CPC earnings summary for the authenticated creator. The enabled flag indicates whether the earnings program is currently active.

Response 200

{
  "enabled": true,
  "summary": {
    "finalized_count": 320,
    "finalized_amount_cents": 6400,
    "today_amount_cents": 120,
    "this_month_amount_cents": 1800,
    "available_balance_cents": 4200,
    "pending_payout_amount_cents": 2000,
    "pending_payout_count": 1,
    "total_paid_cents": 10000,
    "minimum_payout_cents": 500
  }
}

All monetary values are in cents. Divide by 100 to get the dollar amount.

Profile

GET/profile

Returns the authenticated creator's public profile information.

Response 200

{
  "id": 1,
  "name": "Jane Creator",
  "email": "jane@example.com",
  "role": "creator",
  "is_creator": true,
  "profile_photo_url": "https://pasterlink.com/storage/profile-photos/jane.jpg",
  "created_at": "2023-06-01T00:00:00+00:00",
  "profile": {
    "bio": "<p>Making pastes since <strong>2023</strong>.</p>",
    "show_pastes_public": true
  }
}

profile.bio is sanitized HTML, not plain text. Render it as HTML, or strip the tags and decode entities (for example &) before showing it as text. It is null when no bio is set.

HTTP Error Codes

Code	Envelope code	Meaning
401	UNAUTHORIZED	Missing, invalid, or expired API token
403	FORBIDDEN	Account is not a Creator Mode account, or you tried to update or delete another account's paste
404	NOT_FOUND	Paste not found, or (on GET) owned by another account
422	VALIDATION_FAILED	Invalid request body — see `details`
409	IDEMPOTENCY_KEY_REUSED	The `Idempotency-Key` was already used with a different payload
429	— (not the envelope)	Rate limit of 60 requests per minute per key exceeded — retry after `Retry-After` seconds
500	—	Server error

Security Notes

Never expose API keys in client-side or public code.
Revoke a compromised key immediately from Creator Dashboard → API Keys.
Each token can be revoked independently — create one per integration.
Token hashes are stored server-side; the plaintext is displayed only once at creation.
body_tier1 content is never included in API responses.