API Reference
Complete reference for the 1ly API.
Base URL
https://1ly.store/apiAuthentication
Most endpoints require authentication via session cookie (for web) or wallet signature (for agents).
Public Endpoints
Get Store
Fetch a public store profile and links.
GET /api/store/:usernameResponse:
{
"profile": {
"username": "joe",
"displayName": "Joe's APIs",
"bio": "Weather and data APIs",
"avatarUrl": "https://..."
},
"links": [...],
"stats": {
"totalLinks": 5,
"totalSales": 150
}
}Get Link
Fetch a single link's details.
GET /api/link/:username/:slugFor paid API links, returns HTTP 402 with payment requirements.
Discovery Endpoints
Explore (Human UI)
Search the marketplace for stores and links.
GET /api/explore?q=weather&category=data&sort=popularQuery Parameters:
| Param | Description |
|---|---|
q | Search query |
category | Filter by category |
minPrice | Minimum price |
maxPrice | Maximum price |
sort | popular, newest, rating |
page | Page number |
limit | Results per page (default: 20) |
Discover (Agent API)
Fast, minimal payload for AI agents.
GET /api/discover?q=weather&limit=10Optimized for < 100ms response time.
Authenticated Endpoints
Profile
GET /api/profile # Get current user profile
PATCH /api/profile # Update profileLinks Management
GET /api/links # List your links
POST /api/links # Create link
PATCH /api/links/:id # Update link
DELETE /api/links/:id # Delete linkEarnings
GET /api/earnings/summary # Total, available, today, month
GET /api/earnings/top-links # Top performing links
GET /api/earnings/transactions # Transaction historyWallets
GET /api/wallets # List saved wallets
PATCH /api/wallets # Add/update walletWithdrawals
POST /api/withdrawals # Request withdrawal
GET /api/withdrawals # Withdrawal historyPayment Flow
x402 Payment (for API links)
GET /api/link/:username/:slug→ Returns 402- Build transaction with payment
GET /api/link/:username/:slugwithX-PAYMENTheader- Receive proxied API response
See x402 Protocol for details.
Error Responses
All errors return JSON:
{
"error": "Error message here",
"code": "ERROR_CODE"
}| Status | Meaning |
|---|---|
| 400 | Bad request |
| 401 | Unauthorized |
| 402 | Payment required |
| 404 | Not found |
| 500 | Server error |