Spotted API Explorer

POST /api/v1/auth/login

Password

POST /api/v1/auth/signup

Username

Password

GET /api/v1/auth/me

Requires: Bearer Token

GET /api/v1/public/nearby

No Auth Required ✓

Get cell statistics (post count and active boost count) for nearby H3 cells. Default radius is 10km.

Latitude *

Longitude *

Radius (meters)

GET /api/v1/public/posts/cell/:h3Cell

No Auth Required ✓

Get all posts in a specific H3 cell. Use this when a user clicks on a hexagon on the map.

H3 Cell Index * (15 hex characters)

Limit

Offset

GET /api/v1/public/boosts/cell/:h3Cell

No Auth Required ✓

Get all boosts covering a specific H3 cell. Use this when a user clicks on a hexagon on the map.

H3 Cell Index * (15 hex characters)

Limit

Offset

GET /api/v1/public/posts/boost/:boostId

No Auth Required ✓

Get all posts associated with a specific boost campaign.

Boost ID * (UUID)

Limit

Offset

GET /api/v1/public/posts/:postId

No Auth Required

Get a single post by its ID. Returns sanitized public data.

Post ID * (UUID)

GET /api/v1/public/boosts/:boostId

No Auth Required

Get a single boost campaign by its ID. Returns full boost details with live_status.

Boost ID * (UUID)

GET /api/v1/public/feed

No Auth Required ✓

Combined nearby posts + active boosts in a single efficient call. No authentication required.

Latitude *

Longitude *

Radius (meters)

Limit (posts)

Offset

GET /api/v1/public/posts/nearby

No Auth Required ✓

Get nearby posts without authentication. Returns sanitized public data only.

Latitude *

Longitude *

Radius (meters)

GET /api/v1/public/boosts/nearby

No Auth Required ✓

Get active boost campaigns near a location without authentication.

Latitude *

Longitude *

Radius (meters)

ℹ️ Public API Info

Public endpoints are designed for:

Pre-login browsing experience
Faster responses (no auth overhead)

Rate Limit: 30 requests/minute (vs 100 for authenticated)

Sanitized Fields: Sensitive data like user_id, privy_address, device_id are stripped from responses.

GET /api/v1/user/profile

Requires: Bearer Token

Returns the authenticated user's profile (username, pfp, email)

PATCH /api/v1/user/profile

Requires: Bearer Token, multipart/form-data

Update username and/or profile picture. Both fields are optional.

Username

Profile Picture

Click to select profile picture (max 5MB, images only)

📱 Mobile Integration Guide click to toggle

Content-Type: multipart/form-data (do NOT set manually — let the HTTP client handle it)

Form fields:

Field	Type	Required	Constraints
`username`	text	optional	1–50 chars
`pfp`	file (image)	optional	image/* only, max 5MB

Swift (UIKit / SwiftUI)

let url = URL(string: "https://spotted-backend-v1-production.up.railway.app/api/v1/user/profile")!
let boundary = "Boundary-\(UUID().uuidString)"

var request = URLRequest(url: url)
request.httpMethod = "PATCH"
request.setValue("Bearer \(token)", forHTTPHeaderField: "Authorization")
request.setValue("multipart/form-data; boundary=\(boundary)", forHTTPHeaderField: "Content-Type")

var body = Data()

// username (optional text field)
body.append("--\(boundary)\r\n")
body.append("Content-Disposition: form-data; name=\"username\"\r\n\r\n")
body.append("\(username)\r\n")

// pfp (optional image file)
if let imageData = image.jpegData(compressionQuality: 0.8) {
    body.append("--\(boundary)\r\n")
    body.append("Content-Disposition: form-data; name=\"pfp\"; filename=\"pfp.jpg\"\r\n")
    body.append("Content-Type: image/jpeg\r\n\r\n")
    body.append(imageData)
    body.append("\r\n")
}

body.append("--\(boundary)--\r\n")
request.httpBody = body

let (data, _) = try await URLSession.shared.data(for: request)

React Native (expo-image-picker)

const form = new FormData();
form.append('username', 'newname');
form.append('pfp', {
  uri: image.uri,                      // from ImagePicker result
  type: image.mimeType || 'image/jpeg',
  name: image.fileName || 'pfp.jpg',
});

const res = await fetch(
  'https://spotted-backend-v1-production.up.railway.app/api/v1/user/profile',
  {
    method: 'PATCH',
    headers: { Authorization: `Bearer ${token}` },
    body: form,  // do NOT set Content-Type
  }
);

Response (same for GET and PATCH)

{
  "username": "testing",
  "pfp": "https://zflpksgmfzewqaefjpqn.supabase.co/storage/v1/object/public/users/.../pfp_17707.png",
  "email": "testing@testing.com"
}

Key notes: pfp URL is public (no auth needed to display) · old pfp auto-deleted on replacement · send only changed fields · pfp field name must be exactly pfp

GET /api/v1/user/wallet/balance

Requires: Bearer Token

Returns the authenticated user's Shelbynet wallet balances (APT and ShelbyUSD)

GET /api/v1/user/posts

Requires: Bearer Token

Returns posts created by the authenticated user

Limit

Offset

POST /api/v1/user/upload

Requires: Bearer Token, multipart/form-data

Upload a file to Shelbynet with geolocation metadata. Creates a post in the database.

Drop file here or click to browse

Custom Filename (optional)

Latitude *

Longitude *

GET /api/v1/user/posts/nearby?latitude={latitude}&longitude={longitude}&radius={radius}

Requires: Bearer Token

Search for posts near a location using H3 geospatial indexing

Latitude *

Longitude *

Radius (meters)

GET /api/v1/user/boosts/nearby?latitude={latitude}&longitude={longitude}&radius={radius}

Requires: Bearer Token

Search for active boost campaigns near a location

Latitude *

Longitude *

Radius (meters)

Map Visualization

Visualizes nearby results with H3 hexagons and boost coverage areas

POST /api/v1/admin/boosts

Requires: Bearer Token (Admin)

Create a new boost campaign with location targeting

Location Nickname *

Latitude *

Longitude *

Radius (meters) *

Task Headline *

Task Image (optional)

📷 Click to select task image (max 10MB)

Task Description

Start At (UTC) *

Expire At (UTC) *

GET /api/v1/admin/boosts?live_status={live_status}

Requires: Bearer Token (Admin)

Status Filter

Limit

Offset

DELETE /api/v1/admin/boosts/:boostId

Requires: Bearer Token (Admin)

Boost ID *

Boosts Map

GET /api/v1/admin/posts?boost_status={boost_status}

Requires: Bearer Token (Admin)

Returns all posts in the system with optional filtering

Boost Status

Limit

Offset

PUT /api/v1/admin/posts/:postId

Requires: Bearer Token (Admin)

Update a post's boost status

Post ID *

New Boost Status *

📷 Posts (0)

⚡ Boosts (0)