Working with Data - ClashCloud

This guide covers how to paginate, filter, and sort responses, as well as how to handle rate limits and caching when interacting with the ClashCloud API.

Pagination

All collection endpoints (like /v1/news and /v1/projects) support pagination. You can control the results using two query parameters:

page — The page number to retrieve (default: 1).
per_page — The number of items per page (default: 20, maximum: 100).

Example request:

bash

curl "https://api.clashcloud.dev/v1/news?page=1&per_page=10"

The response will include meta and links objects to help you navigate:

json

{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 42
  },
  "links": {
    "first": "...",
    "last": "...",
    "prev": null,
    "next": "https://api.clashcloud.dev/v1/news?page=2"
  }
}

Filtering and Sorting

You can filter and sort the results of collection endpoints using query parameters.

Filter by Tag

Pass the tag slug to the tag parameter:

bash

curl "https://api.clashcloud.dev/v1/news?tag=laravel"

Search

Use the search parameter to filter by title or excerpt:

curl "https://api.clashcloud.dev/v1/news?search=release"

Sorting

Use the sort parameter. A minus sign (-) indicates descending order. If no minus sign is provided, the order is ascending.

Supported sort columns for News: published_at, created_at, title. Supported sort columns for Projects: created_at, title.

bash

#Newest first
curl "https://api.clashcloud.dev/v1/news?sort=-published_at"

#Alphabetical by title
curl "https://api.clashcloud.dev/v1/projects?sort=title"

Private Endpoints Reference

The following endpoints require a valid Bearer token (see the Authentication guide).

Method	Endpoint	Description
GET	/v1/me	Get your private profile (including email and 2FA status)
PATCH	/v1/me	Update your profile (username, social links)
GET	/v1/me/projects	List your projects (including pending approval)
POST	/v1/me/projects	Create a new project
PATCH	/v1/me/projects/{id}	Update your project
DELETE	/v1/me/projects/{id}	Delete your project
GET	/v1/me/news	List your news articles (including drafts)
POST	/v1/me/news	Create a new news article
GET	/v1/me/comments	List your comments
DELETE	/v1/me/comments/{id}	Delete your comment (soft-delete)
GET	/v1/me/tokens	List your API tokens
POST	/v1/me/tokens	Create a new API token
DELETE	/v1/me/tokens/{id}	Revoke an API token

Rate Limiting

To ensure fair usage, the API enforces rate limits based on your IP address or user ID.

Endpoint Type	Limit	Key
Public	Endpoints 60 requests / minute	IP Address
Authenticated Endpoints	300 requests / minute	User ID (or IP)
POST /v1/contact	5 requests / minute	IP Address

When you hit the limit, the API will return a 429 Too Many Requests status code. Every response includes the following headers to help you track your usage:

X-RateLimit-Limit — Total requests allowed per minute.
X-RateLimit-Remaining — Requests remaining in the current window.
X-RateLimit-Reset — Timestamp when the limit resets.

Caching with ETags

To save bandwidth and improve performance, all public GET endpoints return an ETag header.

You can pass this ETag back to the server in the If-None-Match header. If the data hasn't changed, the server will respond with a 304 Not Modified status code and no body, saving you from downloading the same JSON again.

bash

#1. Make a request and note the ETag header
curl -I https://api.clashcloud.dev/v1/news

#2. Make the same request with the If-None-Match header
curl -H 'If-None-Match: "your-etag-value"' https://api.clashcloud.dev/v1/news