Developers
API Reference

API Reference

Complete reference for the 1ly API.

Base URL

https://1ly.store/api

Authentication

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/:username

Response:

{
  "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/:slug

For 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=popular

Query Parameters:

ParamDescription
qSearch query
categoryFilter by category
minPriceMinimum price
maxPriceMaximum price
sortpopular, newest, rating
pagePage number
limitResults per page (default: 20)

Discover (Agent API)

Fast, minimal payload for AI agents.

GET /api/discover?q=weather&limit=10

Optimized for < 100ms response time.


Authenticated Endpoints

Profile

GET /api/profile          # Get current user profile
PATCH /api/profile        # Update profile

Links Management

GET /api/links            # List your links
POST /api/links           # Create link
PATCH /api/links/:id      # Update link
DELETE /api/links/:id     # Delete link

Earnings

GET /api/earnings/summary       # Total, available, today, month
GET /api/earnings/top-links     # Top performing links
GET /api/earnings/transactions  # Transaction history

Wallets

GET /api/wallets          # List saved wallets
PATCH /api/wallets        # Add/update wallet

Withdrawals

POST /api/withdrawals     # Request withdrawal
GET /api/withdrawals      # Withdrawal history

Payment Flow

x402 Payment (for API links)

  1. GET /api/link/:username/:slug → Returns 402
  2. Build transaction with payment
  3. GET /api/link/:username/:slug with X-PAYMENT header
  4. Receive proxied API response

See x402 Protocol for details.


Error Responses

All errors return JSON:

{
  "error": "Error message here",
  "code": "ERROR_CODE"
}
StatusMeaning
400Bad request
401Unauthorized
402Payment required
404Not found
500Server error