1. Introduction
the swagsocial API lets you create posts and read data using your own app or bot. all the endpoints start
with /api.
2. Authentication
you can create an API key in settings, then send it with every request that requires auth:
Authorization: Bearer YOUR_API_KEY
keys have permission scopes. currently for now the only scope is posts.write, which is required
for the write endpoints below.
a missing, malformed, or invalid key gets you a 401 Unauthorized. a key that's valid but missing
the required scope gets you a 403 Forbidden. your api key is only ever shown once, right after
you create it, we don't store or return the raw key anywhere after that, only a reference hash and its last
4 characters..
3. Rate Limits
API requests are rate limited to 500 requests per 15 minutes per IP. if you exceed this
limit, the API will respond with a 429 Too Many Requests status code. wait for the rate limit
window to reset before sending more requests.
3.1 Response Format
every JSON response includes a success bool. on failure, an error field explains
what went wrong, and the HTTP status code tells you the category: 400 for a bad request,
401 for missing/invalid auth, 403 for insufficient permissions, 404
for something that doesn't exist, and 429 for rate limiting.
4. Stats
4.1 GET /api/stats/users
returns the total number of registered users.
curl https://swag.nomaakip.xyz/api/stats/users
4.2 GET /api/stats/posts
returns the total number of posts.
curl https://swag.nomaakip.xyz/api/stats/posts
5. Users
5.1 GET /api/me
returns your own account info (excluding ip). you can access either using a api key or your current session if logged in.
curl https://swag.nomaakip.xyz/api/me \ -H "Authorization: Bearer YOUR_API_KEY"
5.2 GET /api/@:username
returns a user's public profile and their posts.
curl https://swag.nomaakip.xyz/api/@squirrel
6. Last.fm
if a user has connected their last.fm account, you can check what they're currently listening to. this endpoint is public and doesn't require auth.
6.1 GET /api/nowplaying/:username
returns the track a user is currently scrobbling on last.fm, or null if they aren't
connected, aren't listening to anything right now, or last.fm is unreachable.
curl https://swag.nomaakip.xyz/api/nowplaying/squirrel
{
"success": true,
"nowPlaying": {
"artist": "I Set My Friends on Fire",
"track": "Things That Rhyme With Orange",
"album": "You Can't Spell Slaughter Without Laughter",
"image": "https://lastfm-img.freetls.fastly.net/i/u/174s/c278691ff128d27a0bb9ecc0507bdfeb.png",
"url": "https://www.last.fm/music/I+Set+My+Friends+on+Fire/_/Things+That+Rhyme+With+Orange"
}
}
when nothing is playing, nowPlaying is just null.
7. Posts
post objects only include fields that apply: a reply has parent_id and reply_to, a
top-level post doesn't; mentions only shows up if the post actually mentions someone. media is
always under media, an array of { url, thumb, type }.
7.1 GET /api/post/:id
returns a single post, its parent (if it's a reply), and its replies.
curl https://swag.nomaakip.xyz/api/post/123
7.2 POST /api/post requires posts.write
creates a new post. accepts multipart/form-data with a content field and up to
4 media files.
curl -X POST https://swag.nomaakip.xyz/api/post \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "content=hello from the api"
7.3 POST /api/post/:id/reply requires posts.write
replies to a post. same body format as creating a post. fails if a post is locked.
curl -X POST https://swag.nomaakip.xyz/api/post/123/reply \ -H "Authorization: Bearer YOUR_API_KEY" \ -F "content=swag post"
7.4 POST /api/post/:id/delete requires posts.write
deletes a post you own (or other's if admin).
curl -X POST https://swag.nomaakip.xyz/api/post/123/delete \ -H "Authorization: Bearer YOUR_API_KEY"
8. Conclusion
well, that's really all for the api docs!! i hope you have fun making whatever you will be making with it!!!