REST API documentation

Create a new user account with email and password. Returns access and refresh tokens and emails a link to verify the address. The account can use the API straight away, but its email must be verified within 72 hours of signing up: `email_verification_deadline` in the user object says when, and past it login and refresh return 403 with code EMAIL_NOT_VERIFIED until the address is verified.

{
  "user": {
    "id": 1,
    "username": "janedoe",
    "email": "jane@example.com",
    "display_name": "Jane Doe",
    "email_verified": false,
    "email_verification_deadline": "2026-09-16T09:00:00Z",
    "ask_product_updates": false
  },
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

curl -X POST https://stackness.dev/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "jane@example.com",
    "password": "SecurePass1!",
    "username": "janedoe"
  }'

const res = await fetch("https://stackness.dev/api/v1/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "jane@example.com",
    password: "SecurePass1!",
    username: "janedoe",
  }),
});
const data = await res.json();

Authenticate with email and password. Returns JWT access and refresh tokens. An account whose email is still unverified 72 hours after signing up gets 403 with code EMAIL_NOT_VERIFIED instead, and a fresh verification link is emailed to it.

{
  "user": {
    "id": 1,
    "username": "janedoe",
    "email": "jane@example.com",
    "email_verified": true
  },
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

curl -X POST https://stackness.dev/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com", "password": "SecurePass1!"}'

const res = await fetch("https://stackness.dev/api/v1/auth/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    email: "jane@example.com",
    password: "SecurePass1!",
  }),
});
const data = await res.json();

Exchange a valid refresh token for a new access token. The old refresh token is invalidated. Returns 403 with code EMAIL_NOT_VERIFIED once an unverified account is past its 72-hour grace period.

{
  "access_token": "eyJhbGciOiJI...",
  "refresh_token": "eyJhbGciOiJI..."
}

curl -X POST https://stackness.dev/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJI..."}'

const res = await fetch("https://stackness.dev/api/v1/auth/refresh", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refresh_token: refreshToken }),
});
const data = await res.json();

Invalidate the current refresh token, effectively logging the user out.

{
  "message": "logged out"
}

curl -X POST https://stackness.dev/api/v1/auth/logout \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJhbGciOiJI..."}'

await fetch("https://stackness.dev/api/v1/auth/logout", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ refresh_token: refreshToken }),
});

Redirects the user to GitHub for authorization. After consent, GitHub redirects back to the callback URL. The state GitHub sees is a bare UUID; return_to and tools stay on the server. If GitHub answers with an error, such as a cancelled sign-in, the frontend callback still gets both values back.

302 Redirect to GitHub authorization page

# Open in browser - this endpoint redirects
curl -v "https://stackness.dev/api/v1/auth/github?return_to=%2Fblog%2Fsome-post&tools=611,407"

// Redirect the user in the browser
window.location.href =
  "https://stackness.dev/api/v1/auth/github?return_to=%2Fblog%2Fsome-post&tools=611,407";

Handles the OAuth callback from GitHub. Exchanges the authorization code for tokens and creates or links the user account.

302 Redirect to frontend with tokens

# This endpoint is called by GitHub, not directly
# GitHub redirects to: /api/v1/auth/github/callback?code=...&state=...

// This callback is handled automatically by the OAuth flow
// After redirect, tokens are available via query params

Redirects the user to Google for authorization. After consent, Google redirects back to the callback URL. The state Google sees is a bare UUID; return_to and tools stay on the server. If Google answers with an error, such as a cancelled sign-in, the frontend callback still gets both values back.

302 Redirect to Google authorization page

# Open in browser - this endpoint redirects
curl -v "https://stackness.dev/api/v1/auth/google?return_to=%2Fblog%2Fsome-post&tools=611,407"

// Redirect the user in the browser
window.location.href =
  "https://stackness.dev/api/v1/auth/google?return_to=%2Fblog%2Fsome-post&tools=611,407";

Handles the OAuth callback from Google. Exchanges the authorization code for tokens and creates or links the user account.

302 Redirect to frontend with tokens

# This endpoint is called by Google, not directly
# Google redirects to: /api/v1/auth/google/callback?code=...&state=...

// This callback is handled automatically by the OAuth flow
// After redirect, tokens are available via query params

Email a single-use password reset link to the given address. The response is the same generic 200 whether or not an account exists for that email, so the endpoint cannot be used to probe which emails are registered. OAuth-only accounts can complete the flow to set a password alongside their provider login.

{
  "message": "If an account exists for that email, a password reset link has been sent."
}

curl -X POST https://stackness.dev/api/v1/auth/forgot-password \
  -H "Content-Type: application/json" \
  -d '{"email": "jane@example.com"}'

const res = await fetch("https://stackness.dev/api/v1/auth/forgot-password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "jane@example.com" }),
});
const data = await res.json();

Set a new password using the single-use token from a password reset email. On success all of the user's existing sessions are revoked, so every device must log in again. An invalid or expired token returns 400.

{
  "message": "password has been reset"
}

curl -X POST https://stackness.dev/api/v1/auth/reset-password \
  -H "Content-Type: application/json" \
  -d '{"token": "a1b2c3d4...", "password": "NewSecurePass1!"}'

const res = await fetch("https://stackness.dev/api/v1/auth/reset-password", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: resetToken, password: "NewSecurePass1!" }),
});
const data = await res.json();

Confirm the account's email address with the single-use token from a verification email. No session is needed, so the link works on any device. A token expires after 72 hours; verifying at any time, including after the grace period has blocked login, unblocks the account. An invalid, expired or already used token returns 400 with code INVALID_VERIFICATION_TOKEN.

{
  "message": "email address verified"
}

curl -X POST https://stackness.dev/api/v1/auth/verify-email \
  -H "Content-Type: application/json" \
  -d '{"token": "a1b2c3d4..."}'

const res = await fetch("https://stackness.dev/api/v1/auth/verify-email", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ token: verificationToken }),
});
const data = await res.json();

Email a fresh verification link to the signed-in user, invalidating the previous link. An account that is already verified gets the same 200 with email_verified set to true, and nothing is sent. Takes a JWT access token, not an API key. Limited to 5 requests per 10 minutes per user, and a new link goes out at most once every 2 minutes: a request inside that window returns 429 with code RATE_LIMITED.

{
  "message": "If your email address is not verified yet, a new verification link has been sent.",
  "email_verified": false
}

curl -X POST https://stackness.dev/api/v1/auth/resend-verification \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/auth/resend-verification", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Swap the single-use code issued by a GitHub or Google OAuth callback for tokens. The access token is returned in the body and the refresh token is set as an HttpOnly cookie. Used by the OAuth callback page after the provider redirect; an invalid or expired code returns 401. The body also says where the sign-in started: `return_to` and `tool_ids` as given to the OAuth start route (each left out when empty, and always left out when linking a provider from settings), and `new_user`, true when this sign-in created the account.

{
  "access_token": "eyJhbGciOiJI...",
  "return_to": "/blog/some-post",
  "tool_ids": [611, 407],
  "new_user": true
}

curl -X POST https://stackness.dev/api/v1/auth/oauth/exchange \
  -H "Content-Type: application/json" \
  -d '{"code": "a1b2c3d4..."}'

const res = await fetch("https://stackness.dev/api/v1/auth/oauth/exchange", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ code }),
});
const data = await res.json();

Create an API key for programmatic access. The key (prefixed with "sfk_") is only returned once in the response.

{
  "id": 1,
  "name": "Claude Desktop",
  "key": "sfk_abc123...",
  "created_at": "2025-01-15T10:30:00Z"
}

curl -X POST https://stackness.dev/api/v1/api-keys \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Claude Desktop"}'

const res = await fetch("https://stackness.dev/api/v1/api-keys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Claude Desktop" }),
});
const data = await res.json();

List all API keys for the authenticated user. Key values are not included for security.

{
  "api_keys": [
    {
      "id": 1,
      "name": "Claude Desktop",
      "prefix": "sfk_abc1",
      "created_at": "2025-01-15T10:30:00Z",
      "last_used_at": "2025-01-16T08:00:00Z"
    }
  ]
}

curl https://stackness.dev/api/v1/api-keys \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/api-keys", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Permanently revoke and delete an API key. Any requests using this key will immediately fail.

{
  "message": "api key deleted"
}

curl -X DELETE https://stackness.dev/api/v1/api-keys/1 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/api-keys/1", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Return the full profile of the currently authenticated user, including email and settings. The tool and move counts include every tool and move you hold, private and ended ones too.

{
  "id": 1,
  "username": "janedoe",
  "email": "jane@example.com",
  "display_name": "Jane Doe",
  "bio": "Full-stack developer",
  "job_title": "Senior frontend engineer",
  "avatar_url": "https://cdn.stackness.dev/avatars/1.jpg",
  "mastodon_url": "https://mastodon.social/@janedoe",
  "is_pro": false,
  "onboarding_completed": true,
  "created_at": "2025-01-01T00:00:00Z"
}

curl https://stackness.dev/api/v1/users/me \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/users/me", {
  headers: { Authorization: `Bearer ${token}` },
});
const user = await res.json();

Update the authenticated user's profile fields. Only provided fields are changed.

{
  "id": 1,
  "username": "janedoe",
  "display_name": "Jane Doe",
  "bio": "Updated bio",
  "website": "https://jane.dev"
}

curl -X PATCH https://stackness.dev/api/v1/users/me \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"bio": "Updated bio", "website": "https://jane.dev"}'

const res = await fetch("https://stackness.dev/api/v1/users/me", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ bio: "Updated bio" }),
});
const user = await res.json();

Record that the authenticated user has finished or skipped the onboarding walkthrough. Sets the completion timestamp on the first call and leaves it untouched afterwards, so retries are safe. The flag is returned as onboarding_completed on GET /api/v1/users/me and on the user object embedded in auth responses.

204 No Content

curl -X POST https://stackness.dev/api/v1/users/me/onboarding/complete \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/users/me/onboarding/complete", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

Retrieve a user's public profile by username. A public profile needs no authentication. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual. The tool and move counts are what a visitor sees: the user's public tools and moves that have not ended, and none at all for a banned account. The owner's own GET /api/v1/users/me counts everything they hold.

{
  "id": 1,
  "username": "janedoe",
  "display_name": "Jane Doe",
  "bio": "Full-stack developer",
  "job_title": "Senior frontend engineer",
  "avatar_url": "https://cdn.stackness.dev/avatars/1.jpg",
  "mastodon_url": "https://mastodon.social/@janedoe",
  "followers_count": 42,
  "following_count": 18,
  "stack_count": 12,
  "is_pro": true
}

curl https://stackness.dev/api/v1/users/janedoe

const res = await fetch("https://stackness.dev/api/v1/users/janedoe");
const profile = await res.json();

List the followers of a given user. Supports cursor-based pagination. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual. An unauthenticated caller never sees a follower whose profile_visibility is logged_in: those rows are left out, and hidden_count says how many of the whole list that was, the same on every page. Any signed-in viewer, including through an API key, sees every follower, and hidden_count is omitted.

{
  "users": [
    {
      "id": 2,
      "username": "johndoe",
      "display_name": "John Doe",
      "avatar_url": "https://cdn.stackness.dev/avatars/2.jpg",
      "is_pro": false
    }
  ],
  "next_cursor": 41,
  "has_more": true,
  "hidden_count": 1
}

curl "https://stackness.dev/api/v1/users/janedoe/followers?limit=20"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/followers?limit=20"
);
const data = await res.json();

List the users that a given user is following. Supports cursor-based pagination. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual. An unauthenticated caller never sees a followed user whose profile_visibility is logged_in: those rows are left out, and hidden_count says how many of the whole list that was, the same on every page. Any signed-in viewer, including through an API key, sees every followed user, and hidden_count is omitted.

{
  "users": [
    {
      "id": 3,
      "username": "alice",
      "display_name": "Alice",
      "avatar_url": "https://cdn.stackness.dev/avatars/3.jpg",
      "is_pro": false
    }
  ],
  "has_more": false,
  "hidden_count": 2
}

curl "https://stackness.dev/api/v1/users/janedoe/following?limit=20"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/following?limit=20"
);
const data = await res.json();

Redirects (302) to the profile's Open Graph card at /stck/{username}/opengraph-image/card, a 1200x630 PNG. Returns 404 for an unknown member. A profile set to logged_in draws the site card rather than the member, so this address never exposes a restricted profile.

302 Found, Location: https://stackness.dev/stck/janedoe/opengraph-image/card

curl -L -o og.png https://stackness.dev/api/v1/users/janedoe/og-image

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/og-image"
);
const blob = await res.blob();

Generate a QR code that links to the user's profile. Returns a PNG image. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual.

Binary PNG image (Content-Type: image/png)

curl -o qr.png https://stackness.dev/api/v1/users/janedoe/qr-code

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/qr-code"
);
const blob = await res.blob();

Render the user's newest public move as a self-contained 480x200 SVG badge for READMEs and portfolios. Pin a specific public move with ?move={slug}; a slug that is not one of the user's public moves returns 404. A user with no public moves gets a 200 card that reads "No public moves yet". Cached for five minutes. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual.

SVG image (Content-Type: image/svg+xml)

curl -o move-card.svg "https://stackness.dev/api/v1/users/janedoe/move-card?theme=light"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/move-card?move=cut-cold-starts"
);
const svg = await res.text();

Render the user's profile as a self-contained 400x216 SVG badge for READMEs and portfolios, carrying the avatar, the follower count, the public tool and move counts (public and not ended, the numbers GET /api/v1/users/{username} returns), and a QR code to the profile. Cached for five minutes. A profile whose profile_visibility is logged_in returns 404, as do a deactivated profile, a banned profile and an unknown username.

SVG image (Content-Type: image/svg+xml)

curl -o profile-card.svg "https://stackness.dev/api/v1/users/janedoe/profile-card?theme=light"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/profile-card"
);
const svg = await res.text();

Start following the specified user. You will see their activity in your feed.

{
  "message": "followed",
  "following": true
}

curl -X POST https://stackness.dev/api/v1/users/janedoe/follow \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/users/janedoe/follow", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});

Stop following the specified user. Their activity will no longer appear in your feed.

{
  "message": "unfollowed",
  "following": false
}

curl -X DELETE https://stackness.dev/api/v1/users/janedoe/follow \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/users/janedoe/follow", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Check whether the authenticated user is following the specified user.

{
  "is_following": true
}

curl https://stackness.dev/api/v1/users/janedoe/is-following \
  -H "Authorization: Bearer <token>"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/is-following",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await res.json();

Check in one request whether the authenticated user follows each of up to 50 distinct usernames. Duplicates are collapsed, and unknown or deactivated usernames come back false. An empty list returns 400 INVALID_REQUEST; more than 50 distinct usernames returns 400 TOO_MANY_USERNAMES.

{
  "following": {
    "alex_rust": true,
    "sarah_chen": false
  }
}

curl "https://stackness.dev/api/v1/users/me/following-status?usernames=alex_rust,sarah_chen" \
  -H "Authorization: Bearer <token>"

const res = await fetch(
  "https://stackness.dev/api/v1/users/me/following-status?usernames=alex_rust,sarah_chen",
  { headers: { Authorization: `Bearer ${token}` } }
);
const { following } = await res.json();

Get the full list of tool categories (e.g., Databases, Frontend Frameworks, DevOps).

{
  "categories": [
    {
      "id": 1,
      "name": "Databases",
      "slug": "databases",
      "display_order": 1,
      "description": "Where developers keep state...",
      "tool_count": 24
    }
  ]
}

curl https://stackness.dev/api/v1/categories

const res = await fetch("https://stackness.dev/api/v1/categories");
const data = await res.json();

Everything behind one category hub page: the category with its intro, the tools ranked by user count (the top ten carry twelve weeks of trend points, each counting the public stack entries current at that week's end), the risers and fallers of the last thirty days, the tools most often paired from outside the category, the most popular moves, the slugs whose imported history the page charts, and up to six eligible comparisons between the category's own tools. Risers and fallers are omitted when fewer than three tools qualify. Every count reads public stack entries by owners who are neither banned nor deactivated, and private, friends-only and subscriber-only entries never count: user counts, pairings and the stack entry count behind `indexable` take the entries that have not ended, risers count public additions in the window and fallers public entries that ended in it, each over the current user count. `indexable` is false for a thin category, which renders a short page and stays out of the sitemap. The whole aggregate is cached for an hour. Reads an optional Authorization header: an unauthenticated caller never gets a move whose author has set profile_visibility to logged_in, checked against the author's visibility at the moment of the request rather than when the aggregate was cached, while every count still includes them. Any signed-in viewer, including through an API key, gets every move.

{
  "category": {
    "id": 2,
    "name": "Terminal & Shell",
    "slug": "terminal-shell",
    "display_order": 2,
    "description": "Where developers keep state...",
    "tool_count": 24
  },
  "indexable": true,
  "data_as_of": "2026-09-08T09:14:02Z",
  "tools": [
    {
      "id": 12,
      "name": "Ghostty",
      "slug": "ghostty",
      "description": "GPU-accelerated terminal emulator",
      "logo_url": "https://cdn.stackness.dev/logos/ghostty.png",
      "user_count": 184,
      "categories": [{ "id": 2, "name": "Terminal & Shell", "slug": "terminal-shell", "display_order": 2 }],
      "created_at": "2025-04-02T10:00:00Z",
      "trend": [{ "week": "2026-06-22", "user_count": 151 }]
    }
  ],
  "risers": [
    { "tool_id": 12, "name": "Ghostty", "slug": "ghostty", "count": 33, "total_users": 184, "rate": 17.9 }
  ],
  "fallers": [],
  "pairings": [
    { "tool_id": 45, "name": "Neovim", "slug": "neovim", "count": 6, "user_count": 402 }
  ],
  "moves": [
    {
      "id": 88,
      "slug": "ghostty-quick-terminal-hotkey",
      "title": "Ghostty quick terminal on a hotkey",
      "tools": [{ "id": 12, "name": "Ghostty", "slug": "ghostty" }],
      "is_backdated": false,
      "author": { "id": 3, "username": "sarah_chen", "is_pro": true },
      "reaction_count": 12,
      "comment_count": 4,
      "created_at": "2026-05-11T08:00:00Z",
      "updated_at": "2026-05-11T08:00:00Z"
    }
  ],
  "history_slugs": ["ghostty", "zsh", "fish"],
  "comparisons": [
    {
      "slug": "fish-vs-zsh",
      "tool_a": { "name": "Fish", "slug": "fish" },
      "tool_b": { "name": "Zsh", "slug": "zsh" }
    }
  ]
}

curl https://stackness.dev/api/v1/categories/terminal-shell

const res = await fetch(
  "https://stackness.dev/api/v1/categories/terminal-shell"
);
const data = await res.json();

List tools with optional filtering by category. Supports cursor-based pagination. Each tool's `user_count`, and the popularity order, counts its public stack entries that have not ended, by owners who are neither banned nor deactivated; private, friends-only and subscriber-only entries never count.

{
  "tools": [
    {
      "id": 1,
      "name": "PostgreSQL",
      "slug": "postgresql",
      "description": "Open-source relational database",
      "website": "https://postgresql.org",
      "category": "Databases",
      "user_count": 340
    }
  ],
  "next_cursor": "abc123",
  "has_more": true
}

curl "https://stackness.dev/api/v1/tools?category=databases&limit=20"

const res = await fetch(
  "https://stackness.dev/api/v1/tools?category=databases&limit=20"
);
const data = await res.json();

Full-text search across tool names and descriptions.

{
  "tools": [
    {
      "id": 1,
      "name": "PostgreSQL",
      "slug": "postgresql",
      "description": "Open-source relational database",
      "user_count": 340
    }
  ]
}

curl "https://stackness.dev/api/v1/tools/search?q=postgres"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/search?q=postgres"
);
const data = await res.json();

Get full details for a specific tool including description, website, category, and usage stats. `user_count` counts the tool's public stack entries that have not ended, by owners who are neither banned nor deactivated: the members GET /api/v1/tools/{slug}/users lists. `has_real_members` is false when none of those entries belongs to a real member, either because there are none or because every one belongs to a generated test account; a member whose profile is visible to signed-in visitors only still counts as real. `logo_dark_url` is present only for a logo that needs a dark-theme variant. `comparisons` lists the /compare/{a}-vs-{b} pages the tool appears on - the pairs someone picked by hand that also clear the per-tool data floors. It is empty while the comparison tree is switched out of search indexes. `about` is a short text about the tool in our own words, written only from the sourced facts (paragraphs separated by a blank line); it is absent until the nightly enrichment has written one. `facts` lists sourced facts as `{key, value, date?, source_url}` rows, where `source_url` is the page the value was read from and `key` is one of `developer`, `license`, `language`, `platforms`, `first_release` (an ISO date at day, month or year precision), `latest_release` (the version, with its `date` when known), `github_stars` (an integer), `repository_since` (an ISO date), `archived` (present only for an archived repository), `repository`, `docs`, `pricing` or `download` (URLs); it is an empty array for a tool nothing was found for. `facts_checked_at` is when the facts were last fetched, absent before the first run. `indexable` says whether the page clears the content floor: when false the page still serves, with `noindex, follow`, and is left out of the sitemap.

{
  "id": 1,
  "name": "PostgreSQL",
  "slug": "postgresql",
  "description": "Open-source relational database",
  "website": "https://postgresql.org",
  "category": {
    "id": 1,
    "name": "Databases",
    "slug": "databases"
  },
  "user_count": 340,
  "has_real_members": true,
  "created_at": "2025-01-01T00:00:00Z",
  "comparisons": [
    {
      "pair": "mysql-vs-postgresql",
      "tool": {
        "id": 12,
        "name": "MySQL",
        "slug": "mysql",
        "logo_url": "https://cdn.stackness.dev/logos/mysql.png",
        "logo_dark_url": "https://cdn.stackness.dev/logos/mysql-dark.png"
      }
    }
  ],
  "about": "PostgreSQL is an open-source relational database developed by the PostgreSQL Global Development Group. Teams use it as the main store for web applications, analytics and geospatial data.",
  "facts": [
    {
      "key": "developer",
      "value": "PostgreSQL Global Development Group",
      "source_url": "https://www.wikidata.org/wiki/Q192490"
    },
    {
      "key": "license",
      "value": "PostgreSQL License",
      "source_url": "https://www.wikidata.org/wiki/Q192490"
    },
    {
      "key": "latest_release",
      "value": "18.0",
      "date": "2025-09-25",
      "source_url": "https://github.com/postgres/postgres"
    },
    {
      "key": "github_stars",
      "value": "18644",
      "source_url": "https://github.com/postgres/postgres"
    },
    {
      "key": "docs",
      "value": "https://www.postgresql.org/docs/",
      "source_url": "https://postgresql.org"
    }
  ],
  "facts_checked_at": "2026-09-29T09:14:00Z",
  "indexable": true
}

curl https://stackness.dev/api/v1/tools/postgresql

const res = await fetch("https://stackness.dev/api/v1/tools/postgresql");
const tool = await res.json();

List the members who list this tool publicly today: public stack entries that have not ended, by owners who are neither banned nor deactivated. Supports cursor-based pagination. Reads an optional Authorization header. Any signed-in viewer, including through an API key, gets the list that agrees with the tool's `user_count`. An unauthenticated caller never sees a member whose profile_visibility is logged_in: those rows are left out, `user_count` still counts them, and hidden_count says how many of the whole list that was, the same on every page. hidden_count is omitted when it is 0.

{
  "users": [
    {
      "id": 1,
      "username": "janedoe",
      "display_name": "Jane Doe",
      "avatar_url": "https://cdn.stackness.dev/avatars/1.jpg",
      "is_pro": false
    }
  ],
  "next_cursor": 812,
  "has_more": true,
  "hidden_count": 2
}

curl "https://stackness.dev/api/v1/tools/postgresql/users?limit=10"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/postgresql/users?limit=10"
);
const data = await res.json();

Return the approved tools among the given ids, in the order asked, in the same tile shape as GET /api/v1/tools/suggestions. Unknown and unapproved ids are left out. Used to show the tools a reader picked before signing up.

{
  "tools": [
    {
      "tool_id": 611,
      "name": "Socket",
      "slug": "socket",
      "logo_url": "https://cdn.stackness.dev/logos/socket.png",
      "description": "Supply chain security for open source dependencies",
      "category": { "id": 9, "name": "Security", "slug": "security" },
      "reason": "popular",
      "score": 0
    }
  ]
}

curl "https://stackness.dev/api/v1/tools/lookup?ids=611,407"

const res = await fetch("https://stackness.dev/api/v1/tools/lookup?ids=611,407");
const data = await res.json();

Power a tool picker: given the slugs a user has already selected, returns tools commonly used alongside them, scored by how many of the selected tools each candidate is paired with. With no selection it returns trending tools. The list is topped up with popular tools from the selection's categories so it is never empty, and excludes the selected tools plus, when authenticated, everything already in your stack.

{
  "tools": [
    {
      "tool_id": 5,
      "name": "Redis",
      "slug": "redis",
      "logo_url": "https://cdn.stackness.dev/logos/redis.png",
      "description": "In-memory data store",
      "category": { "id": 2, "name": "Databases", "slug": "databases" },
      "reason": "used_with:postgresql",
      "score": 180
    }
  ]
}

curl "https://stackness.dev/api/v1/tools/suggestions?selected=postgresql,go&limit=24"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/suggestions?selected=postgresql,go&limit=24"
);
const data = await res.json();

Get tools commonly used alongside this one, based on how many members list both in their public stacks today (public entries that have not ended, by owners who are neither banned nor deactivated). Each peer carries its categories so a caller can tell which of them sit in the same category as the tool being viewed. Co-usage says nothing about which pairs have a comparison page: those are picked by hand and listed in `comparisons` on GET /api/v1/tools/{slug}.

{
  "tools": [
    {
      "tool_id": 5,
      "name": "Redis",
      "slug": "redis",
      "logo_url": "https://cdn.stackness.dev/logos/redis.png",
      "user_count": 180,
      "categories": [
        { "id": 3, "name": "Databases", "slug": "databases" }
      ]
    }
  ]
}

curl "https://stackness.dev/api/v1/tools/postgresql/also-used-with"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/postgresql/also-used-with"
);
const data = await res.json();

Get the adoption trend for a tool over time: one point per week, counting the public stack entries current at that week's end (added by then and not ended by then). The last point equals the tool's `user_count`.

{
  "tool": "postgresql",
  "data_points": [
    { "date": "2025-01-06", "user_count": 300 },
    { "date": "2025-01-13", "user_count": 320 },
    { "date": "2025-01-20", "user_count": 340 }
  ]
}

curl https://stackness.dev/api/v1/tools/postgresql/trend

const res = await fetch(
  "https://stackness.dev/api/v1/tools/postgresql/trend"
);
const data = await res.json();

Submit a tool to be added to the database. Submitted tools are reviewed before becoming public.

{
  "id": 500,
  "name": "My New Tool",
  "slug": "my-new-tool",
  "status": "pending",
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/tools \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My New Tool", "website_url": "https://example.com"}'

const res = await fetch("https://stackness.dev/api/v1/tools", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My New Tool",
    website_url: "https://example.com",
  }),
});
const data = await res.json();

Get the activity feed for a specific tool (moves, stack additions, etc.). Only events of public stack entries appear, ended ones included since a removal is an event too; an entry made private later takes its events with it. Reads an optional Authorization header: an unauthenticated caller never sees the events of a member whose profile_visibility is logged_in, and any signed-in viewer, including through an API key, sees them as usual.

{
  "items": [
    {
      "id": "feed_123",
      "type": "stack_add",
      "user": { "username": "janedoe", "display_name": "Jane Doe" },
      "tool": { "name": "PostgreSQL", "slug": "postgresql" },
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "abc123",
  "has_more": true
}

curl "https://stackness.dev/api/v1/tools/postgresql/feed?limit=10"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/postgresql/feed?limit=10"
);
const data = await res.json();

Get the imported popularity history for a tool as labelled time series, one per source, metric, and granularity combination. Values come from external sources in each source's own unit, so series are displayed separately and never summed. Each point's bucket is the start date of the month or year it covers. A tool with no imported history returns an empty series list; an unknown source or metric returns 400.

{
  "series": [
    {
      "source": "so_survey",
      "source_label": "Stack Overflow developer survey",
      "source_url": "https://survey.stackoverflow.co/2024",
      "metric": "usage_share_pct",
      "metric_label": "Usage share",
      "unit": "% of respondents",
      "granularity": "year",
      "confidence": "high",
      "origin": "imported",
      "points": [
        { "bucket": "2023-01-01", "value": 45.6, "is_estimated": false },
        { "bucket": "2024-01-01", "value": 48.7, "is_estimated": false }
      ]
    }
  ]
}

curl "https://stackness.dev/api/v1/tools/postgresql/history?source=so_survey&metric=usage_share_pct"

const res = await fetch(
  "https://stackness.dev/api/v1/tools/postgresql/history?source=so_survey"
);
const data = await res.json();

One row per external dataset that has imported history stored, with its oldest and newest bucket, how many datapoints and how many tools or moves it covers, and whether it refreshes automatically or waits for a manual export. It is what tells you a dataset has stopped receiving data: a source whose newest bucket is months old is frozen, not empty. Buckets are the first day of the month or year they cover. Sources come back in alphabetical order.

{
  "sources": [
    {
      "source": "npm",
      "source_label": "npm downloads",
      "refresh": "automatic",
      "oldest_bucket": "2015-01-01",
      "newest_bucket": "2026-08-01",
      "row_count": 48210,
      "target_count": 312
    },
    {
      "source": "sede_tags",
      "source_label": "Stack Exchange data explorer",
      "refresh": "manual",
      "oldest_bucket": "2008-09-01",
      "newest_bucket": "2026-08-01",
      "row_count": 20251,
      "target_count": 244
    }
  ],
  "checked_at": "2026-09-11T08:00:00Z"
}

curl "https://stackness.dev/api/v1/history/sources"

const res = await fetch("https://stackness.dev/api/v1/history/sources");
const data = await res.json();

Everything behind a /compare/{a}-vs-{b} page: both tools with their user counts and twelve weeks of trend points (counted as on GET /api/v1/tools/{slug} and its trend) and the net change, their imported history series, their three most popular public moves, how many members list both, how many moved from one to the other in each direction and the months those moves span, the pairings they share and the ones only each has, and the curated verdict when one is published. The slugs may come in either order; `pair`, `tool_a` and `tool_b` always carry the canonical alphabetical order, so a caller can redirect to it. A page exists only for a pair someone picked by hand, and only once both of its tools clear the data floors (a shared category, and a minimum number of members and imported history series each). Shared users, switch counts and pairings are reported as facts about the pair; they never decide whether it has a page. A shared user lists both tools in public entries that have not ended; a switch needs two public entries, the one left behind ended. An unknown or unapproved tool returns 404 with code `NOT_FOUND`; a pair with no page returns 404 with code `NOT_ELIGIBLE`. `noindex` is true while the comparison tree is switched out of search indexes, and for any pair without a published verdict: the page still serves, but only a pair with hand-written framing is indexable or listed in the sitemap feed. Reads an optional Authorization header: an unauthenticated caller never gets a move whose author has set profile_visibility to logged_in, and when the verdict's author has, the verdict is returned without its author. Any signed-in viewer, including through an API key, gets both as usual.

{
  "pair": "neovim-vs-vs-code",
  "tool_a": {
    "id": 45,
    "name": "Neovim",
    "slug": "neovim",
    "description": "Hyperextensible Vim-based text editor",
    "website_url": "https://neovim.io",
    "logo_url": "https://cdn.stackness.dev/logos/neovim.png",
    "is_approved": true,
    "user_count": 402,
    "categories": [{ "id": 1, "name": "Editor & IDE", "slug": "editor-ide", "display_order": 1 }],
    "created_at": "2025-01-10T09:00:00Z",
    "trend": [
      { "week": "2026-06-22", "user_count": 371 },
      { "week": "2026-09-07", "user_count": 402 }
    ],
    "trend_delta": 31,
    "history": [
      {
        "source": "so_survey",
        "source_label": "Stack Overflow developer survey",
        "source_url": "https://survey.stackoverflow.co",
        "metric": "usage_share_pct",
        "metric_label": "Usage share",
        "unit": "% of respondents",
        "granularity": "year",
        "confidence": "high",
        "origin": "imported",
        "points": [
          { "bucket": "2024-01-01", "value": 12.5, "is_estimated": false },
          { "bucket": "2025-01-01", "value": 14.1, "is_estimated": false }
        ]
      }
    ],
    "moves": [
      {
        "id": 88,
        "slug": "moved-my-config-to-lazy-nvim",
        "title": "Moved my config to lazy.nvim",
        "tools": [{ "id": 45, "name": "Neovim", "slug": "neovim" }],
        "is_backdated": false,
        "author": { "id": 3, "username": "sarah_chen", "is_pro": true },
        "reaction_count": 12,
        "comment_count": 4,
        "created_at": "2026-05-11T08:00:00Z",
        "updated_at": "2026-05-11T08:00:00Z"
      }
    ]
  },
  "tool_b": {
    "id": 12,
    "name": "VS Code",
    "slug": "vs-code",
    "is_approved": true,
    "user_count": 1204,
    "categories": [{ "id": 1, "name": "Editor & IDE", "slug": "editor-ide", "display_order": 1 }],
    "created_at": "2024-11-02T09:00:00Z",
    "trend": [
      { "week": "2026-06-22", "user_count": 1188 },
      { "week": "2026-09-07", "user_count": 1204 }
    ],
    "trend_delta": 16,
    "history": [],
    "moves": []
  },
  "shared_users": 96,
  "switched_a_to_b": 7,
  "switched_b_to_a": 23,
  "switch_period": { "from": "2023-02", "to": "2026-08" },
  "pairings": {
    "shared": [
      { "tool_id": 5, "name": "Git", "slug": "git", "users_with_a": 210, "users_with_b": 640 }
    ],
    "only_a": [
      { "tool_id": 61, "name": "tmux", "slug": "tmux", "users_with_a": 118, "users_with_b": 0 }
    ],
    "only_b": [
      { "tool_id": 77, "name": "GitHub Copilot", "slug": "github-copilot", "users_with_a": 0, "users_with_b": 301 }
    ]
  },
  "data_as_of": "2026-09-07T18:02:11Z",
  "verdict": {
    "body": "Neovim suits people who already live in the terminal...",
    "author": { "username": "gordeychuk_s", "display_name": "Sergei Gordeichuk" },
    "updated_at": "2026-09-05T10:00:00Z"
  },
  "noindex": false
}

curl https://stackness.dev/api/v1/compare/vs-code/neovim

const res = await fetch(
  "https://stackness.dev/api/v1/compare/vs-code/neovim"
);
if (res.status === 404) {
  const { code } = await res.json(); // "NOT_FOUND" or "NOT_ELIGIBLE"
}
const data = await res.json();

Add a tool to your personal stack with an optional note about how you use it.

{
  "id": 1,
  "tool": {
    "id": 1,
    "name": "PostgreSQL",
    "slug": "postgresql"
  },
  "personal_note": "Primary database for all projects",
  "visibility": "public",
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/stack/tools \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tool_id": 1, "personal_note": "Primary database"}'

const res = await fetch("https://stackness.dev/api/v1/stack/tools", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tool_id: 1, personal_note: "Primary database" }),
});
const data = await res.json();

Add up to 50 tools in one transaction. Tools already in your stack are skipped and reported instead of failing the call. Public adds publish a single grouped stack update so followers see one card, not one per tool, unless announce is false. Each entry defaults to the tool's first catalog category unless category_id is given.

{
  "added": [
    {
      "id": 12,
      "tool": { "id": 1, "name": "PostgreSQL", "slug": "postgresql" },
      "visibility": "public",
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "skipped": [{ "tool_id": 5, "reason": "already_in_stack" }],
  "stack_update_id": 42
}

curl -X POST https://stackness.dev/api/v1/stack/tools/bulk \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"tools": [{"tool_id": 1}, {"tool_id": 5}], "note": "My starter kit"}'

const res = await fetch("https://stackness.dev/api/v1/stack/tools/bulk", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ tools: [{ tool_id: 1 }, { tool_id: 5 }], note: "My starter kit" }),
});
const data = await res.json();

List all tools in the authenticated user's stack, grouped by category.

{
  "tools": [
    {
      "id": 1,
      "tool": {
        "id": 1,
        "name": "PostgreSQL",
        "slug": "postgresql",
        "category": "Databases"
      },
      "note": "Primary database",
      "added_at": "2025-01-20T10:00:00Z"
    }
  ],
  "total": 12
}

curl https://stackness.dev/api/v1/stack/tools \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/stack/tools", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Update the note, category, dates, or visibility of a tool in your stack. Another user's public entry answers 403; another user's entry that is not public answers the same 404 as an id that does not exist.

{
  "id": 1,
  "tool": {
    "id": 1,
    "name": "PostgreSQL",
    "slug": "postgresql"
  },
  "personal_note": "Updated note",
  "visibility": "public",
  "updated_at": "2025-01-20T10:00:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/stack/tools/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"personal_note": "Updated note"}'

const res = await fetch("https://stackness.dev/api/v1/stack/tools/1", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ personal_note: "Updated note" }),
});
const data = await res.json();

Remove a tool from your stack. This does not delete the tool from the database. Another user's public entry answers 403; another user's entry that is not public answers the same 404 as an id that does not exist.

{
  "message": "tool removed from stack"
}

curl -X DELETE https://stackness.dev/api/v1/stack/tools/1 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/stack/tools/1", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

View the public stack for any user by their username. The response carries the subspace grid (user-defined groups with ordered tools, moves, and clusters plus per-tile layout state) alongside the legacy category grouping. Tracks, the optional level above subspaces, come in their own list; each subspace names its track in track_id, or null when it sits outside every track. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual.

{
  "categories": [
    {
      "category": { "id": 2, "name": "Databases", "slug": "databases", "display_order": 1 },
      "tools": [{ "id": 12, "tool": { "id": 1, "name": "PostgreSQL", "slug": "postgresql" } }]
    }
  ],
  "tracks": [{ "id": 3, "name": "Backend", "slug": "backend", "position": 0 }],
  "subspaces": [
    {
      "id": 4,
      "name": "Daily drivers",
      "slug": "daily-drivers",
      "color": "indigo",
      "position": 0,
      "start_collapsed": false,
      "width": "full",
      "track_id": 3,
      "items": [
        {
          "type": "tool",
          "position": 0,
          "size": "featured",
          "use_image_background": false,
          "dim_image_background": false,
          "user_tool": {
            "id": 12,
            "tool": { "id": 1, "name": "PostgreSQL", "slug": "postgresql" },
            "personal_note": "Primary database",
            "reactions": [{ "emoji": "fire", "count": 3, "reacted": false }],
            "comment_count": 1
          }
        },
        {
          "type": "move",
          "position": 1,
          "size": "normal",
          "use_image_background": false,
          "dim_image_background": false,
          "move": { "id": 7, "slug": "prompt-driven-tdd", "title": "Prompt-driven TDD", "reactions": [], "comment_count": 0 }
        }
      ],
      "clusters": [
        {
          "id": 2,
          "name": "Little helpers",
          "position": 2,
          "items": [{ "type": "tool", "position": 0, "size": "mini", "cluster_id": 2, "user_tool": { "id": 15 } }]
        }
      ]
    }
  ],
  "ungrouped": { "items": [], "clusters": [] }
}

curl https://stackness.dev/api/v1/users/janedoe/stack

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/stack"
);
const data = await res.json();

Create a named, colored subspace on your profile grid. The anchor slug is derived from the name once and stays stable across renames, so deep links keep working.

{
  "id": 4,
  "name": "Daily drivers",
  "slug": "daily-drivers",
  "color": "indigo",
  "position": 3,
  "start_collapsed": false,
  "width": "full",
  "track_id": null,
  "created_at": "2026-08-25T12:00:00Z",
  "updated_at": "2026-08-25T12:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/stack/subspaces \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Daily drivers", "color": "indigo"}'

const res = await fetch("https://stackness.dev/api/v1/stack/subspaces", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Daily drivers", color: "indigo" }),
});

Set the top-to-bottom order of your subspaces. Positions follow the order of the given ids.

204 No Content

curl -X PATCH https://stackness.dev/api/v1/stack/subspaces/reorder \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"subspace_ids": [4, 2, 7]}'

await fetch("https://stackness.dev/api/v1/stack/subspaces/reorder", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ subspace_ids: [4, 2, 7] }),
});

Rename or recolor a subspace, set whether it starts collapsed, set its panel width, or move it into or out of a track. The anchor slug never changes on rename.

{
  "id": 4,
  "name": "Weekend experiments",
  "slug": "daily-drivers",
  "color": "rose",
  "position": 3,
  "start_collapsed": false,
  "width": "half",
  "track_id": 3,
  "created_at": "2026-08-25T12:00:00Z",
  "updated_at": "2026-08-25T12:30:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/stack/subspaces/4 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"color": "rose"}'

await fetch("https://stackness.dev/api/v1/stack/subspaces/4", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ color: "rose" }),
});

Delete a subspace. Its tiles and clusters are not removed - they fall back to the ungrouped grid at the end of the profile.

204 No Content

curl -X DELETE https://stackness.dev/api/v1/stack/subspaces/4 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/stack/subspaces/4", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List your tracks in display order. A track is a named role or area of work, such as Backend or Mobile, that groups subspaces on your profile.

{
  "tracks": [
    {
      "id": 3,
      "name": "Backend",
      "slug": "backend",
      "position": 0,
      "created_at": "2026-09-28T12:00:00Z",
      "updated_at": "2026-09-28T12:00:00Z"
    }
  ]
}

curl https://stackness.dev/api/v1/stack/tracks \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/stack/tracks", {
  headers: { Authorization: `Bearer ${token}` },
});
const { tracks } = await res.json();

Create a track after your others and, optionally, move subspaces into it in the same call. The slug behind ?track= links is derived from the name once and stays stable across renames. A stack holds at most 12 tracks.

{
  "id": 5,
  "name": "Mobile",
  "slug": "mobile",
  "position": 1,
  "created_at": "2026-09-28T12:00:00Z",
  "updated_at": "2026-09-28T12:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/stack/tracks \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Mobile", "subspace_ids": [6, 7]}'

const res = await fetch("https://stackness.dev/api/v1/stack/tracks", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Mobile", subspace_ids: [6, 7] }),
});

Set the order of your tracks. Positions follow the order of the given ids.

204 No Content

curl -X PATCH https://stackness.dev/api/v1/stack/tracks/reorder \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"track_ids": [5, 3]}'

await fetch("https://stackness.dev/api/v1/stack/tracks/reorder", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ track_ids: [5, 3] }),
});

Rename a track. The slug never changes, so existing ?track= links keep working.

{
  "id": 5,
  "name": "Apps",
  "slug": "mobile",
  "position": 1,
  "created_at": "2026-09-28T12:00:00Z",
  "updated_at": "2026-09-28T12:30:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/stack/tracks/5 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Apps"}'

await fetch("https://stackness.dev/api/v1/stack/tracks/5", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Apps" }),
});

Delete a track. Its subspaces and everything in them stay on your profile, outside any track.

204 No Content

curl -X DELETE https://stackness.dev/api/v1/stack/tracks/5 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/stack/tracks/5", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Create a named cluster - a single tile that holds mini chips. Assign items to it through the layout endpoint.

{
  "id": 2,
  "name": "Little helpers",
  "subspace_id": 4,
  "position": 5,
  "created_at": "2026-08-25T12:00:00Z",
  "updated_at": "2026-08-25T12:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/stack/clusters \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Little helpers", "subspace_id": 4}'

const res = await fetch("https://stackness.dev/api/v1/stack/clusters", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Little helpers", subspace_id: 4 }),
});

Rename a cluster.

{
  "id": 2,
  "name": "Python helpers",
  "subspace_id": 4,
  "position": 5,
  "created_at": "2026-08-25T12:00:00Z",
  "updated_at": "2026-08-25T12:45:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/stack/clusters/2 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Python helpers"}'

await fetch("https://stackness.dev/api/v1/stack/clusters/2", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Python helpers" }),
});

Ungroup a cluster: its mini chips are promoted back to small tiles in place, then the cluster tile is removed.

204 No Content

curl -X DELETE https://stackness.dev/api/v1/stack/clusters/2 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/stack/clusters/2", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Batch-save the profile grid arrangement: item positions, sizes, subspace and cluster membership, image background flags, and cluster placement in one call. Size is one of featured, wide, tall, normal, small, or mini; items inside a cluster must use size mini.

204 No Content

curl -X PUT https://stackness.dev/api/v1/stack/layout \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"items": [{"type": "tool", "id": 12, "subspace_id": 4, "position": 0, "size": "featured"}]}'

await fetch("https://stackness.dev/api/v1/stack/layout", {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    items: [
      { type: "tool", id: 12, subspace_id: 4, position: 0, size: "featured" },
    ],
  }),
});

Publish a summary of recent changes to your stack as a feed item visible to your followers. Each change carries a change_type (tool_added, tool_removed, move_added, move_retired, subspace_created, subspace_renamed, subspace_removed, or layout_updated) and a target_type (user_tool, move, subspace, or stack). Only rows for your own public stack entries and moves are stored, together with subspace and stack rows; a row naming an entry that is not public, is not yours or no longer exists is dropped, and a publish left with no row answers 400.

{
  "id": 1,
  "user_id": 42,
  "note": "Spring cleaning",
  "changes": [
    { "change_type": "tool_added", "target_type": "user_tool", "target_id": 12, "target_name": "Bun" },
    { "change_type": "subspace_created", "target_type": "subspace", "target_id": 4, "target_name": "Daily drivers" },
    { "change_type": "layout_updated", "target_type": "stack", "target_id": 0, "target_name": "Stack layout" }
  ],
  "published_at": "2025-01-20T10:00:00Z",
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/stack/updates \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"note": "Spring cleaning", "changes": [{"change_type": "tool_added", "target_type": "user_tool", "target_id": 12, "target_name": "Bun"}]}'

const res = await fetch("https://stackness.dev/api/v1/stack/updates", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    note: "Spring cleaning",
    changes: [
      {
        change_type: "tool_added",
        target_type: "user_tool",
        target_id: 12,
        target_name: "Bun",
      },
    ],
  }),
});
const data = await res.json();

Copy one item from someone else's stack into your own. `target_type` picks what is being copied: `user_tool` copies a single stack entry (the tool, its category and its note), `move` copies a move together with the tools it references. Returns 201 with the item that was created. Copying a tool you already have returns 409 with code `TOOL_ALREADY_IN_STACK` - moves have no such guard and may be copied more than once. Copying your own item returns 403, and a source that was deleted or is no longer public returns 404.

{
  "type": "user_tool",
  "user_tool": {
    "id": 812,
    "tool": { "id": 10, "name": "Bun", "slug": "bun" },
    "category": { "id": 3, "name": "Runtime", "slug": "runtime", "display_order": 2 },
    "personal_note": "Faster installs than npm",
    "visibility": "public",
    "is_backdated": false,
    "created_at": "2026-08-28T10:00:00Z",
    "updated_at": "2026-08-28T10:00:00Z",
    "reactions": [],
    "comment_count": 0
  }
}

curl -X POST https://stackness.dev/api/v1/stack/copy \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"target_type": "user_tool", "target_id": 412}'

const res = await fetch("https://stackness.dev/api/v1/stack/copy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ target_type: "user_tool", target_id: 412 }),
});
if (res.status === 409) {
  // code: "TOOL_ALREADY_IN_STACK" - the tool is already in your stack
}
const data = await res.json();

Every dated stack entry for a user - tools and moves, active and retired - with category, dates, reactions and comment counts. Powers the stack-over-time chart, so the list is not paginated. The owner (authenticated as that user) sees private entries; every other viewer sees public-visibility entries only. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual.

{
  "items": [
    {
      "type": "user_tool",
      "id": 12,
      "tool": { "id": 1, "name": "PostgreSQL", "slug": "postgresql" },
      "category": { "id": 2, "name": "Databases", "slug": "databases", "display_order": 1 },
      "personal_note": "Primary database",
      "start_date": "2023-04-01T00:00:00Z",
      "end_date": "2025-01-01T00:00:00Z",
      "comment_count": 3,
      "reactions": [{ "emoji": "fire", "count": 2, "reacted": false }]
    },
    {
      "type": "move",
      "id": 7,
      "title": "Prompt-driven TDD",
      "start_date": "2024-06-01T00:00:00Z",
      "comment_count": 0,
      "reactions": []
    }
  ]
}

curl "https://stackness.dev/api/v1/users/janedoe/history"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/history"
);
const data = await res.json();

Get a single published stack update by id, including its note and the changes it announced. Each change names what it touched: change_type is one of tool_added, tool_removed, move_added, move_retired, subspace_created, subspace_renamed, subspace_removed, or layout_updated, and target_type is user_tool, move, subspace, or stack. Anyone but the publisher gets a user_tool or move row only while its entry still exists and is public; an update left with no row and no note answers the same 404 as an id that does not exist.

{
  "id": 42,
  "user_id": 1,
  "note": "Swapped my test runner and retired an old workflow.",
  "changes": [
    {
      "change_type": "tool_added",
      "target_type": "user_tool",
      "target_id": 20,
      "target_name": "Vitest",
      "target_slug": "vitest"
    },
    {
      "change_type": "move_retired",
      "target_type": "move",
      "target_id": 7,
      "target_name": "Prompt-Driven TDD Workflow",
      "target_slug": "prompt-driven-tdd-workflow"
    }
  ],
  "published_at": "2025-01-20T10:00:00Z",
  "created_at": "2025-01-20T10:00:00Z"
}

curl https://stackness.dev/api/v1/stack/updates/42 \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/stack/updates/42", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Create a new move - a technique, workflow, or approach you use. Moves appear in your followers' feeds.

{
  "id": 1,
  "slug": "prompt-driven-tdd-workflow",
  "title": "Prompt-Driven TDD Workflow",
  "description": "Write the test prompt first, then implement until green...",
  "tools": [{ "name": "Vitest", "slug": "vitest" }],
  "visibility": "public",
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/moves \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Prompt-Driven TDD Workflow",
    "description": "Write the test prompt first...",
    "tool_ids": [20]
  }'

const res = await fetch("https://stackness.dev/api/v1/moves", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Prompt-Driven TDD Workflow",
    tool_ids: [20],
  }),
});
const data = await res.json();

List all moves created by the authenticated user. Supports cursor-based pagination.

{
  "moves": [
    {
      "id": 1,
      "slug": "prompt-driven-tdd-workflow",
      "title": "Prompt-Driven TDD Workflow",
      "visibility": "public",
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "abc123",
  "has_more": false
}

curl "https://stackness.dev/api/v1/moves?limit=10" \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/moves?limit=10", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Get full details for a specific move by id or slug. The slug is minted once at creation and never changes, so it is safe to store. You get your own moves in every visibility; another user's move only while it is public and its owner's account is active, and otherwise the same 404 as an id that does not exist.

{
  "id": 1,
  "slug": "prompt-driven-tdd-workflow",
  "title": "Prompt-Driven TDD Workflow",
  "description": "Write the test prompt first, then implement until green...",
  "tools": [{ "name": "Vitest", "slug": "vitest" }],
  "visibility": "public",
  "created_at": "2025-01-20T10:00:00Z"
}

curl https://stackness.dev/api/v1/moves/1 \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/moves/1", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Update a move you created. Sending tool_ids replaces the move's tools; omit it to leave them unchanged. Another user's public move answers 403; another user's move that is not public answers the same 404 as an id that does not exist.

{
  "id": 1,
  "slug": "prompt-driven-tdd-workflow",
  "title": "Updated title",
  "description": "Updated description",
  "visibility": "public"
}

curl -X PATCH https://stackness.dev/api/v1/moves/1 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title"}'

const res = await fetch("https://stackness.dev/api/v1/moves/1", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "Updated title" }),
});
const data = await res.json();

Permanently delete a move you created. Another user's public move answers 403; another user's move that is not public answers the same 404 as an id that does not exist.

{
  "message": "move deleted"
}

curl -X DELETE https://stackness.dev/api/v1/moves/1 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/moves/1", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List all public moves created by a user. Supports cursor-based pagination. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual.

{
  "moves": [
    {
      "id": 1,
      "slug": "prompt-driven-tdd-workflow",
      "title": "Prompt-Driven TDD Workflow",
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "abc123",
  "has_more": false
}

curl "https://stackness.dev/api/v1/users/janedoe/moves?limit=10"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/moves?limit=10"
);
const data = await res.json();

List public moves across all users with author info plus reaction and comment counts. Supports sorting, text search, category and tool filtering, and cursor-based pagination. Retired moves (those with an end date) and moves by deactivated accounts are excluded. No authentication required. Reads an optional Authorization header: an unauthenticated caller never gets a move whose author has set profile_visibility to logged_in, and any signed-in viewer, including through an API key, gets them as usual.

{
  "moves": [
    {
      "id": 1,
      "slug": "prompt-driven-tdd-workflow",
      "title": "Prompt-Driven TDD Workflow",
      "description": "Write the test prompt first, then implement until green...",
      "category": { "id": 3, "name": "AI Tools", "slug": "ai-tools", "display_order": 3 },
      "tools": [{ "id": 20, "name": "Vitest", "slug": "vitest" }],
      "is_backdated": false,
      "author": {
        "id": 1,
        "username": "janedoe",
        "display_name": "Jane Doe",
        "is_pro": false
      },
      "reaction_count": 12,
      "comment_count": 4,
      "created_at": "2025-01-20T10:00:00Z",
      "updated_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "16_1",
  "has_more": true
}

curl "https://stackness.dev/api/v1/moves/public?sort=popularity&limit=10"

const res = await fetch(
  "https://stackness.dev/api/v1/moves/public?sort=popularity&limit=10"
);
const data = await res.json();

Get full details for a single public-visibility move by id or slug, including author info plus reaction and comment counts. A move that is not public, or whose author is deactivated, returns 404. No authentication required. Returns 404 to an unauthenticated caller when the author has set profile_visibility to logged_in, exactly as for a missing move; any signed-in viewer, including through an API key, sees the move as usual.

{
  "id": 1,
  "slug": "prompt-driven-tdd-workflow",
  "title": "Prompt-Driven TDD Workflow",
  "description": "Write the test prompt first, then implement until green...",
  "category": { "id": 3, "name": "AI Tools", "slug": "ai-tools", "display_order": 3 },
  "tools": [{ "id": 20, "name": "Vitest", "slug": "vitest" }],
  "is_backdated": false,
  "author": {
    "id": 1,
    "username": "janedoe",
    "display_name": "Jane Doe",
    "is_pro": false
  },
  "reaction_count": 12,
  "comment_count": 4,
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:00:00Z"
}

curl https://stackness.dev/api/v1/moves/public/prompt-driven-tdd-workflow

const res = await fetch(
  "https://stackness.dev/api/v1/moves/public/prompt-driven-tdd-workflow"
);
const data = await res.json();

Save a tool or a move to your bookmarks with an optional note. New items start with status "saved". Saving the same target twice returns a 409 conflict. A move you cannot see, a tool that is not approved, or an id that does not exist answers 404 TARGET_NOT_FOUND, checked before the conflict.

{
  "id": 42,
  "target_type": "tool",
  "target_id": 7,
  "status": "saved",
  "note": "Try for the side project",
  "status_changed_at": "2025-01-20T10:00:00Z",
  "created_at": "2025-01-20T10:00:00Z",
  "tool": {
    "id": 7,
    "name": "Neovim",
    "slug": "neovim",
    "description": "Hyperextensible Vim-based text editor",
    "website_url": "https://neovim.io",
    "logo_url": "https://cdn.stackness.dev/logos/neovim.png",
    "categories": [
      { "id": 3, "name": "Editors", "slug": "editors", "display_order": 1 }
    ]
  }
}

curl -X POST https://stackness.dev/api/v1/saved-items \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"target_type": "tool", "target_id": 7, "note": "Try for the side project"}'

const res = await fetch("https://stackness.dev/api/v1/saved-items", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ target_type: "tool", target_id: 7, note: "Try for the side project" }),
});
const data = await res.json();

List the authenticated user's saved items, optionally filtered by status or target type. Cursor-based pagination; next_cursor is only present when has_more is true. Saved tools include an inline tool object with its categories, saved moves an inline move object with the id of the user who wrote it (author_id). A bookmarked move that is no longer public is left out until it turns public again.

{
  "items": [
    {
      "id": 42,
      "target_type": "tool",
      "target_id": 7,
      "status": "trying",
      "note": "Try for the side project",
      "status_changed_at": "2025-01-21T09:00:00Z",
      "created_at": "2025-01-20T10:00:00Z",
      "tool": {
        "id": 7,
        "name": "Neovim",
        "slug": "neovim",
        "description": "Hyperextensible Vim-based text editor",
        "website_url": "https://neovim.io",
        "logo_url": "https://cdn.stackness.dev/logos/neovim.png",
        "categories": [
          { "id": 3, "name": "Editors", "slug": "editors", "display_order": 1 }
        ]
      }
    },
    {
      "id": 41,
      "target_type": "move",
      "target_id": 12,
      "status": "saved",
      "status_changed_at": "2025-01-19T14:00:00Z",
      "created_at": "2025-01-19T14:00:00Z",
      "move": {
        "id": 12,
        "slug": "tdd-with-claude",
        "title": "TDD with Claude",
        "description": "Let the tests drive the agent",
        "author_id": 5
      }
    }
  ],
  "next_cursor": 41,
  "has_more": true
}

curl "https://stackness.dev/api/v1/saved-items?status=trying&limit=20" \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/saved-items?status=trying&limit=20", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Check whether the authenticated user has already saved a specific tool or move. When saved is false the item field is omitted. A bookmarked move that is no longer public reports saved false.

{
  "saved": true,
  "item": {
    "id": 42,
    "target_type": "tool",
    "target_id": 7,
    "status": "saved",
    "note": "Try for the side project",
    "status_changed_at": "2025-01-20T10:00:00Z",
    "created_at": "2025-01-20T10:00:00Z"
  }
}

curl "https://stackness.dev/api/v1/saved-items/check?target_type=tool&target_id=7" \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/saved-items/check?target_type=tool&target_id=7", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Update the status or note of a saved item you own. At least one field must be provided. Changing the status also updates status_changed_at. A bookmark of a move that is no longer public answers the same 404 as an id that does not exist.

{
  "id": 42,
  "target_type": "tool",
  "target_id": 7,
  "status": "trying",
  "note": "Try for the side project",
  "status_changed_at": "2025-01-21T09:00:00Z",
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/saved-items/42 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"status": "trying"}'

const res = await fetch("https://stackness.dev/api/v1/saved-items/42", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ status: "trying" }),
});
const data = await res.json();

Remove an item from your bookmarks. Returns 204 with no body on success; deleting an item you do not own returns 403. A bookmark of a move that is no longer public can still be deleted.

Empty response (204 no content)

curl -X DELETE https://stackness.dev/api/v1/saved-items/42 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/saved-items/42", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List root comments on a target, oldest first, with up to 3 of each root's replies interleaved after it; reply_count carries the full reply total per root. Pass parent_id to page through all replies of one root comment instead; total_count is then that parent's full reply count, otherwise it counts every comment on the target, roots and replies included. Reads an optional Authorization header: a user_tool or move target that is not public, or no longer exists, answers 404 TARGET_NOT_FOUND to everyone but its owner, and a parent_id on such a target answers 404 PARENT_NOT_FOUND like a missing parent. An unauthenticated caller gets the same 404s for a user_tool, move or stack_update target whose owner has set profile_visibility to logged_in; blog_post targets are never gated by their author. A game target (target_id is the id from GET /api/v1/games) has a thread only for a signed-in member who has unlocked that game, and only once it is available: everyone else, including for a game that is a mystery, coming soon or unknown, and every non-admin while achievements are switched off (see GET /api/v1/features), gets 404 TARGET_NOT_FOUND, and a parent_id on that thread gets 404 PARENT_NOT_FOUND. Comments that a user with a logged-in-only profile posted elsewhere stay in the list for an unauthenticated caller, without user and with user_id 0. Any signed-in viewer, including through an API key, sees every author as usual, and total_count and reply_count count every comment for everyone.

{
  "comments": [
    {
      "id": 42,
      "user_id": 7,
      "target_type": "move",
      "target_id": 12,
      "body": "Great write-up, we use the same setup",
      "reply_count": 1,
      "created_at": "2025-01-20T10:00:00Z",
      "updated_at": "2025-01-20T10:00:00Z",
      "user": {
        "id": 7,
        "username": "sarah_chen",
        "display_name": "Sarah Chen",
        "avatar_url": "https://stackness.dev/avatars/sarah_chen.png"
      }
    },
    {
      "id": 43,
      "user_id": 9,
      "target_type": "move",
      "target_id": 12,
      "body": "Same here, thanks for sharing",
      "parent_id": 42,
      "reply_count": 0,
      "created_at": "2025-01-20T10:05:00Z",
      "updated_at": "2025-01-20T10:05:00Z",
      "user": {
        "id": 9,
        "username": "dev_marco",
        "display_name": "Marco Ruiz",
        "avatar_url": "https://stackness.dev/avatars/dev_marco.png"
      }
    }
  ],
  "total_count": 2,
  "has_more": false
}

curl "https://stackness.dev/api/v1/comments?target_type=move&target_id=12"

const res = await fetch("https://stackness.dev/api/v1/comments?target_type=move&target_id=12");
const data = await res.json();

Create a comment on a target entity, or reply to a root comment via parent_id (threads are one level deep, so replying to a reply is rejected). Comments containing profanity are rejected. The content owner is notified, and a reply also notifies the parent comment's author, unless the target is not public, when only its owner hears about it. A user_tool or move target that is not public, or does not exist, answers 404 TARGET_NOT_FOUND to everyone but its owner, before parent_id is checked. A game has no owner, so a comment on one notifies nobody and a reply notifies only the parent comment's author; only a member who has unlocked the available game can post on it, and anyone else gets 404 TARGET_NOT_FOUND under the same rule as listing. Returns 201 with the created comment.

{
  "id": 44,
  "user_id": 7,
  "target_type": "move",
  "target_id": 12,
  "body": "Great write-up, we use the same setup",
  "reply_count": 0,
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/comments \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"target_type": "move", "target_id": 12, "body": "Great write-up"}'

const res = await fetch("https://stackness.dev/api/v1/comments", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ target_type: "move", target_id: 12, body: "Great write-up" }),
});
const data = await res.json();

Update the body of one of your comments. Only the comment owner can edit; the same length and profanity checks as creation apply. A comment on a game first needs the caller to pass that game's thread rule from GET /api/v1/comments, or it answers 404 TARGET_NOT_FOUND. Returns the updated comment.

{
  "id": 44,
  "user_id": 7,
  "target_type": "move",
  "target_id": 12,
  "body": "Updated comment text",
  "reply_count": 0,
  "created_at": "2025-01-20T10:00:00Z",
  "updated_at": "2025-01-20T10:15:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/comments/44 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"body": "Updated comment text"}'

const res = await fetch("https://stackness.dev/api/v1/comments/44", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ body: "Updated comment text" }),
});
const data = await res.json();

Delete a comment. Allowed for the comment owner and for the owner of the content the comment is on. A game has no owner, so only the author deletes a comment on one, after passing that game's thread rule from GET /api/v1/comments, or it answers 404 TARGET_NOT_FOUND. Returns 204 with an empty body.

204 no content (empty response body)

curl -X DELETE https://stackness.dev/api/v1/comments/44 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/comments/44", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List reactions on a target grouped by emoji, sorted alphabetically, with aggregate counts. When called with a valid Authorization header, reacted is true for each emoji the caller has reacted with; for anonymous callers it is always false. A user_tool or move target that is not public, or does not exist, answers 404 TARGET_NOT_FOUND to everyone but its owner.

{
  "reactions": [
    {
      "emoji": "fire",
      "count": 3,
      "reacted": true
    },
    {
      "emoji": "thumbsup",
      "count": 5,
      "reacted": false
    }
  ]
}

curl "https://stackness.dev/api/v1/reactions?target_type=move&target_id=12"

const res = await fetch("https://stackness.dev/api/v1/reactions?target_type=move&target_id=12");
const data = await res.json();

List reactions on a target grouped by emoji, sorted alphabetically, with the full count and up to 12 reactors per emoji, oldest reaction first. Reads an optional Authorization header: a user_tool or move target that is not public, or does not exist, answers 404 TARGET_NOT_FOUND to everyone but its owner. An unauthenticated caller gets the same 404 for a user_tool, move or stack_update target whose owner has set profile_visibility to logged_in, and never sees a reactor with a logged-in-only profile: the count still includes them, and the next reactor takes their place among the 12. Any signed-in viewer, including through an API key, sees every reactor.

{
  "reactions": [
    {
      "emoji": "fire",
      "count": 3,
      "users": [
        {
          "id": 7,
          "username": "sarah_chen",
          "display_name": "Sarah Chen",
          "avatar_url": "https://stackness.dev/avatars/sarah_chen.png"
        }
      ]
    }
  ]
}

curl "https://stackness.dev/api/v1/reactions/users?target_type=move&target_id=12"

const res = await fetch("https://stackness.dev/api/v1/reactions/users?target_type=move&target_id=12");
const data = await res.json();

Toggle your reaction on a target entity. Adding a new emoji returns 201 with the created reaction and created true; sending the same emoji again removes it and returns 200 with created false and no reaction object. Adding a reaction notifies the content owner. A user_tool or move target that is not public, or does not exist, answers 404 TARGET_NOT_FOUND to everyone but its owner, and nothing is written.

{
  "reaction": {
    "id": 88,
    "user_id": 7,
    "target_type": "move",
    "target_id": 12,
    "emoji": "fire"
  },
  "created": true
}

curl -X POST https://stackness.dev/api/v1/reactions \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"target_type": "move", "target_id": 12, "emoji": "fire"}'

const res = await fetch("https://stackness.dev/api/v1/reactions", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ target_type: "move", target_id: 12, emoji: "fire" }),
});
const data = await res.json();

Delete a reaction by ID. Only the user who created the reaction can delete it. Returns 204 with an empty body.

204 no content (empty response body)

curl -X DELETE https://stackness.dev/api/v1/reactions/88 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/reactions/88", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Get a chronological feed of activity from users you follow: stack changes, moves and stack updates.

{
  "items": [
    {
      "id": "feed_456",
      "type": "move",
      "user": { "username": "janedoe", "display_name": "Jane Doe" },
      "move": { "title": "Prompt-Driven TDD Workflow" },
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "abc123",
  "has_more": true
}

curl "https://stackness.dev/api/v1/feed/my?limit=20" \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/feed/my?limit=20", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Get the updates feed: recent activity of the users you follow. An event whose stack entry or move is not public, or no longer exists, is left out, and so is each stack update row naming one; a stack update left with no row and no note is skipped. Pages still hold limit items whenever more exist.

{
  "items": [
    {
      "id": "feed_789",
      "type": "stack_update",
      "user": { "username": "johndoe" },
      "title": "Q1 Stack Refresh",
      "created_at": "2025-01-20T09:00:00Z"
    }
  ],
  "next_cursor": "def456",
  "has_more": true
}

curl "https://stackness.dev/api/v1/feed/updates?limit=20" \
  -H "Authorization: Bearer <token>"

const res = await fetch(
  "https://stackness.dev/api/v1/feed/updates?limit=20",
  { headers: { Authorization: `Bearer ${token}` } }
);
const data = await res.json();

Get the public activity feed for a specific user. Returns 404 to an unauthenticated caller when the owner has set profile_visibility to logged_in; any signed-in viewer, including through an API key, sees the profile as usual. Anyone but the owner sees no event whose stack entry or move is not public or no longer exists, and no stack update row naming one; a stack update left with no row and no note is skipped. Pages still hold limit items whenever more exist.

{
  "items": [
    {
      "id": "feed_101",
      "type": "stack_add",
      "tool": { "name": "Bun", "slug": "bun" },
      "created_at": "2025-01-20T10:00:00Z"
    }
  ],
  "next_cursor": "ghi789",
  "has_more": false
}

curl "https://stackness.dev/api/v1/users/janedoe/feed?limit=20"

const res = await fetch(
  "https://stackness.dev/api/v1/users/janedoe/feed?limit=20"
);
const data = await res.json();

List the authenticated user's notifications, newest first. type is one of follow, reaction, comment, copy, achievement, or game_unlocked; target_type is one of user_tool, move, stack_update, user, blog_post, user_achievement, or game. An achievement notification announces one earned level, its actor is the recipient themselves, and it carries an achievement object with the key, level and name; it is created only while achievements are switched on (see GET /api/v1/features) and is never emailed. A game_unlocked notification says a game is open to the recipient: its target_type is game, target_id is the game's id, its actor is the recipient themselves, and it carries a game object with the game's slug and name. It is in-app only and never emailed, not even in the digest. target_owner names the user who owns the target and is absent once that content is deleted (or, for a blog post, unpublished) - it is not always the recipient, since a reply notifies the parent comment's author about an item on someone else's profile. target_slug is set only on blog_post and game targets that still resolve and is what the post's /blog/{slug} URL, or the game's /games/{slug} page, is built from. A game target has no target_owner at all; it reaches someone only as a reply on that game's comment thread. Cursor-based pagination; next_cursor is only present when has_more is true.

{
  "notifications": [
    {
      "id": 120,
      "type": "follow",
      "target_type": "user",
      "target_id": 1,
      "is_read": false,
      "created_at": "2025-01-20T10:00:00Z",
      "actor": {
        "id": 2,
        "username": "johndoe",
        "display_name": "John Doe",
        "avatar_url": "https://cdn.stackness.dev/avatars/2.jpg"
      },
      "target_owner": {
        "id": 1,
        "username": "janedoe",
        "display_name": "Jane Doe"
      }
    },
    {
      "id": 119,
      "type": "reaction",
      "target_type": "user_tool",
      "target_id": 15,
      "is_read": true,
      "created_at": "2025-01-19T18:30:00Z",
      "actor": {
        "id": 3,
        "username": "alice",
        "display_name": "Alice"
      },
      "target_owner": {
        "id": 1,
        "username": "janedoe",
        "display_name": "Jane Doe"
      }
    },
    {
      "id": 118,
      "type": "comment",
      "target_type": "stack_update",
      "target_id": 88,
      "is_read": true,
      "created_at": "2025-01-19T12:00:00Z",
      "actor": {
        "id": 4,
        "username": "toyblackhat",
        "display_name": "Toy Black Hat"
      },
      "target_owner": {
        "id": 4,
        "username": "toyblackhat",
        "display_name": "Toy Black Hat"
      }
    },
    {
      "id": 117,
      "type": "reaction",
      "target_type": "blog_post",
      "target_id": 12,
      "is_read": true,
      "created_at": "2025-01-18T09:15:00Z",
      "actor": {
        "id": 3,
        "username": "alice",
        "display_name": "Alice"
      },
      "target_owner": {
        "id": 1,
        "username": "janedoe",
        "display_name": "Jane Doe"
      },
      "target_slug": "stackness-is-live-on-product-hunt"
    },
    {
      "id": 116,
      "type": "game_unlocked",
      "target_type": "game",
      "target_id": 1,
      "is_read": false,
      "created_at": "2025-01-17T08:00:00Z",
      "actor": {
        "id": 1,
        "username": "janedoe",
        "display_name": "Jane Doe"
      },
      "target_slug": "lonny-eagle",
      "game": {
        "slug": "lonny-eagle",
        "name": "Lonny Eagle Amateur Skater 4"
      }
    }
  ],
  "next_cursor": 116,
  "has_more": true
}

curl "https://stackness.dev/api/v1/notifications?limit=20" \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/notifications?limit=20", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Get the number of unread notifications for the authenticated user.

{
  "count": 3
}

curl https://stackness.dev/api/v1/notifications/unread-count \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/notifications/unread-count", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Mark a single notification as read. Returns 204 with no body; a notification that does not exist or is not yours returns 404.

Empty response (204 no content)

curl -X PATCH https://stackness.dev/api/v1/notifications/120/read \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/notifications/120/read", {
  method: "PATCH",
  headers: { Authorization: `Bearer ${token}` },
});

Mark all of the authenticated user's unread notifications as read and return how many were updated. No request body is required.

{
  "marked_count": 5
}

curl -X POST https://stackness.dev/api/v1/notifications/read-all \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/notifications/read-all", {
  method: "POST",
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Get tools trending across the platform based on recent adoption velocity: public stack entries added in the window, ended ones included, by owners who are neither banned nor deactivated. `user_count` counts the public entries that have not ended. Always returns at most 10 tools. The window widens from weekly to monthly, quarterly and all-time when the requested one is too quiet; the window actually used is echoed back.

{
  "tools": [
    {
      "id": 20,
      "name": "Vite",
      "slug": "vite",
      "user_count": 450,
      "trend_score": 92
    }
  ]
}

curl "https://stackness.dev/api/v1/discover/trending-tools?period=weekly&category=ai-tools"

const res = await fetch(
  "https://stackness.dev/api/v1/discover/trending-tools?period=weekly&category=ai-tools"
);
const data = await res.json();

Get the most popular moves on the platform right now. Only public moves that have not ended rank, by owners who are neither banned nor deactivated, and only reactions on them count. Always returns at most 10 moves, with the same widening window as trending tools. Reads an optional Authorization header: an unauthenticated caller never gets a move whose author has set profile_visibility to logged_in, checked at the moment of the request, and the list still fills from the cached ranking. Any signed-in viewer, including through an API key, gets them as usual.

{
  "moves": [
    {
      "move_id": 5,
      "title": "Prompt-Driven TDD Workflow",
      "username": "janedoe",
      "reaction_count": 42,
      "comment_count": 7
    }
  ]
}

curl "https://stackness.dev/api/v1/discover/trending-moves?category=ai-tools"

const res = await fetch(
  "https://stackness.dev/api/v1/discover/trending-moves?category=ai-tools"
);
const data = await res.json();

Get the top users leaderboard. Rows come in three tiers: people with at least one public, not ended tool first, then people without one, then generated accounts (is_bot). Inside a tier users are ranked by follower count, ties broken by user id ascending, so a person with no followers can rank above a generated account with many. Deactivated accounts are left out. Each row carries is_bot for generated accounts and the move_count and tool_count a visitor sees on the public profile (public and not ended, zero for a banned account); display_name, avatar_url and bio are omitted when empty. Always returns at most 10 users; the endpoint takes no parameters. Reads an optional Authorization header: an unauthenticated caller never sees a user whose profile_visibility is logged_in, checked at the moment of the request, and the list still fills with the next users. Any signed-in viewer, including through an API key, sees them as usual.

{
  "users": [
    {
      "user_id": 1,
      "username": "janedoe",
      "display_name": "Jane Doe",
      "avatar_url": "https://example.com/avatars/janedoe.png",
      "bio": "Backend engineer who writes about Go and Postgres.",
      "is_pro": true,
      "is_bot": false,
      "follower_count": 1200,
      "move_count": 20,
      "tool_count": 25
    }
  ]
}

curl https://stackness.dev/api/v1/discover/top-users

const res = await fetch(
  "https://stackness.dev/api/v1/discover/top-users"
);
const data = await res.json();

Get tools with the fastest adoption growth over the past week. Always returns at most 10 tools, with the same widening window as trending tools: window reports the period that answered (weekly, monthly, quarterly or all_time). growth_rate is recent_adds as a percentage of total_users, and only tools with at least 3 users qualify. recent_adds counts public stack entries added in the window, ended ones included; total_users counts the public entries that have not ended; both leave out owners who are banned or deactivated.

{
  "tools": [
    {
      "tool_id": 30,
      "name": "Bun",
      "slug": "bun",
      "logo_url": "https://example.com/logos/bun.png",
      "description": "All-in-one JavaScript runtime and toolkit",
      "recent_adds": 6,
      "total_users": 12,
      "growth_rate": 50
    }
  ],
  "window": "weekly"
}

curl "https://stackness.dev/api/v1/discover/rising-tools?category=ai-tools"

const res = await fetch(
  "https://stackness.dev/api/v1/discover/rising-tools?category=ai-tools"
);
const data = await res.json();

Full-text search across tools, users, and moves. Filter by type for narrower results. Reads an optional Authorization header: an unauthenticated caller never finds a user whose profile_visibility is logged_in, or that user's moves, and any signed-in viewer, including through an API key, finds them as usual.

{
  "results": [
    {
      "type": "tool",
      "tool": { "name": "PostgreSQL", "slug": "postgresql" }
    },
    {
      "type": "user",
      "user": { "username": "janedoe", "display_name": "Jane Doe" }
    }
  ]
}

curl "https://stackness.dev/api/v1/search?q=postgres&type=tools"

const res = await fetch(
  "https://stackness.dev/api/v1/search?q=postgres&type=tools"
);
const data = await res.json();

The hand-curated stack showcases behind /stacks, alphabetically by title. Each showcase presents a few public profiles whose owners agreed to be featured and the tools they have in common. Members are checked on every read: someone who opts out, makes their profile logged-in only, is banned or deactivates drops out at once. A showcase with fewer than three eligible members is left out. `updated_at` is the later of the showcase's own edit and its newest member stack change.

{
  "stacks": [
    {
      "slug": "indie-hacker-stack",
      "title": "Indie hacker stack",
      "intro": "Solo founders who ship and run a product alone...",
      "member_count": 6,
      "updated_at": "2026-09-20T08:12:44Z"
    }
  ]
}

curl https://stackness.dev/api/v1/stacks

const res = await fetch("https://stackness.dev/api/v1/stacks");
const data = await res.json();

One published showcase: its title and intro, the eligible members in the order they were curated (username, display name, avatar and the number of public tools in their stack), and the tools held by at least two of them. Each tool row carries its categories and `member_count`, read against the showcase's `member_count` as "{count} of {members}". Only public, current stack entries count. `data_as_of` is the newest public stack change among the members. An unknown slug, a draft and a showcase with fewer than three eligible members all return 404 with code `NOT_FOUND`.

{
  "slug": "indie-hacker-stack",
  "title": "Indie hacker stack",
  "intro": "Solo founders who ship and run a product alone...",
  "updated_at": "2026-09-20T08:12:44Z",
  "data_as_of": "2026-09-20T08:12:44Z",
  "member_count": 3,
  "members": [
    {
      "username": "sarah_chen",
      "display_name": "Sarah Chen",
      "avatar_url": "https://cdn.stackness.dev/avatars/1.png",
      "tool_count": 9
    }
  ],
  "tools": [
    {
      "slug": "next-js",
      "name": "Next.js",
      "logo_url": "https://cdn.stackness.dev/logos/next-js.png",
      "logo_dark_url": "https://cdn.stackness.dev/logos/next-js-dark.png",
      "member_count": 3,
      "categories": [{ "slug": "frameworks", "name": "Frameworks" }]
    }
  ]
}

curl https://stackness.dev/api/v1/stacks/indie-hacker-stack

const res = await fetch(
  "https://stackness.dev/api/v1/stacks/indie-hacker-stack"
);
const data = await res.json();

Compute stacked popularity series for tools or moves over a time window. Requires a supporter subscription - accounts without one receive 403. Tool values count the public stack entries active in each bucket, by owners who are neither banned nor deactivated; move values are cumulative reaction counts on public moves that have not ended. Bands are picked by peak activity in the window, and each response includes the top rising and falling entries by growth percentage (999.99 marks a series that rose from zero). Results are cached server side for 6 hours.

{
  "buckets": ["2025-01-06", "2025-01-13", "2025-01-20"],
  "series": [
    {
      "id": 1,
      "name": "PostgreSQL",
      "slug": "postgresql",
      "logo_url": "https://cdn.stackness.dev/logos/postgresql.png",
      "values": [118, 124, 131]
    }
  ],
  "rising": [
    {
      "id": 1,
      "name": "PostgreSQL",
      "growth_pct": 11.0
    }
  ],
  "falling": [
    {
      "id": 7,
      "name": "Grunt",
      "growth_pct": -12.5
    }
  ]
}

curl "https://stackness.dev/api/v1/trends/waves?type=tools&range=6m&granularity=week" \
  -H "Authorization: Bearer <token>"

const res = await fetch(
  "https://stackness.dev/api/v1/trends/waves?type=tools&range=6m&granularity=week",
  { headers: { Authorization: `Bearer ${token}` } },
);
const data = await res.json();

Create a new organization. The creator becomes its owner. A new organization starts on the solo plan with a single seat and no teams; upgrade through billing to invite more members. Fails with 409 ORG_SLUG_TAKEN when the slug is in use or reserved (for example new, create, settings, admin or api).

{
  "id": 12,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "plan": "solo",
  "seat_count": 1,
  "max_seats": 1,
  "created_at": "2025-01-20T10:00:00Z",
  "role": "owner",
  "member_count": 1,
  "team_count": 0,
  "settings": {
    "team_views_counts_only": false,
    "min_group_size": 5
  }
}

curl -X POST https://stackness.dev/api/v1/orgs \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Dev Team", "slug": "acme", "description": "Building the future of developer tools."}'

const res = await fetch("https://stackness.dev/api/v1/orgs", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Acme Dev Team", slug: "acme" }),
});
const data = await res.json();

List every organization the authenticated user belongs to, with the user's role in each: owner, admin or member.

{
  "organizations": [
    {
      "id": 12,
      "name": "Acme Dev Team",
      "slug": "acme",
      "role": "owner"
    }
  ]
}

curl https://stackness.dev/api/v1/orgs \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Get an organization's profile, plan and seat usage, the viewer's role, member and team counts, and its settings. Members only. `team_views_counts_only` and `min_group_size` are stored and returned only for now.

{
  "id": 12,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "logo_url": "https://cdn.stackness.dev/orgs/acme.png",
  "website": "https://acme.dev",
  "plan": "pro",
  "seat_count": 4,
  "max_seats": 10,
  "created_at": "2025-01-20T10:00:00Z",
  "role": "owner",
  "member_count": 4,
  "team_count": 1,
  "settings": {
    "team_views_counts_only": false,
    "min_group_size": 5
  }
}

curl https://stackness.dev/api/v1/orgs/acme \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Update an organization's name, description, logo or website (owner or admin). Omitted fields are left unchanged; the full organization is returned.

{
  "id": 12,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "logo_url": "https://cdn.stackness.dev/orgs/acme.png",
  "website": "https://acme.dev",
  "plan": "pro",
  "seat_count": 4,
  "max_seats": 10,
  "created_at": "2025-01-20T10:00:00Z",
  "role": "owner",
  "member_count": 4,
  "team_count": 1,
  "settings": {
    "team_views_counts_only": false,
    "min_group_size": 5
  }
}

curl -X PATCH https://stackness.dev/api/v1/orgs/acme \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Building the future of developer tools."}'

const res = await fetch("https://stackness.dev/api/v1/orgs/acme", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ description: "Building the future of developer tools." }),
});
const data = await res.json();

Delete an organization (owner only), together with its teams, memberships and invitations. Cancels the organization's Stripe subscription if one exists. Returns 204 with no body.

204 no content

curl -X DELETE https://stackness.dev/api/v1/orgs/acme \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/orgs/acme", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

Update the organization's privacy settings (owner or admin). Omitted fields are left unchanged; the full organization is returned. `min_group_size` must be between 5 and 50, otherwise the request fails with 400 VALIDATION_ERROR. Both settings are stored and returned only for now.

{
  "id": 12,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "logo_url": "https://cdn.stackness.dev/orgs/acme.png",
  "website": "https://acme.dev",
  "plan": "pro",
  "seat_count": 4,
  "max_seats": 10,
  "created_at": "2025-01-20T10:00:00Z",
  "role": "owner",
  "member_count": 4,
  "team_count": 1,
  "settings": {
    "team_views_counts_only": false,
    "min_group_size": 8
  }
}

curl -X PATCH https://stackness.dev/api/v1/orgs/acme/settings \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"min_group_size": 8}'

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/settings", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ min_group_size: 8 }),
});
const data = await res.json();

List the members of an organization with their roles and the teams each one belongs to. Members only. Offset-paginated: the page size defaults to 50 and is capped at 100. The `id` of each entry is the membership ID used to change or remove it.

{
  "members": [
    {
      "id": 3,
      "user_id": 42,
      "username": "sarah_chen",
      "display_name": "Sarah Chen",
      "avatar_url": "https://cdn.stackness.dev/avatars/sarah.png",
      "role": "owner",
      "teams": [
        {
          "id": 31,
          "name": "Acme Dev Team",
          "slug": "acme",
          "role": "lead"
        }
      ]
    }
  ],
  "total_count": 4,
  "has_more": false
}

curl https://stackness.dev/api/v1/orgs/acme/members \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/members", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Change an organization member's role (owner only). Setting the role to owner transfers ownership and makes the current owner an admin. The owner's own role only changes through a transfer (400 CANNOT_CHANGE_OWNER_ROLE). Returns 204 with no body.

204 no content

curl -X PATCH https://stackness.dev/api/v1/orgs/acme/members/3 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"role": "admin"}'

await fetch("https://stackness.dev/api/v1/orgs/acme/members/3", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ role: "admin" }),
});

Remove a member from an organization (owner or admin). The owner cannot be removed, and only the owner can remove an admin. The member's team memberships in the organization go with it, and the seat count and Stripe subscription quantity are updated. Returns 204 with no body.

204 no content

curl -X DELETE https://stackness.dev/api/v1/orgs/acme/members/3 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/orgs/acme/members/3", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List every invitation to the organization with its status (owner or admin). Status is one of pending, accepted, declined, cancelled, or expired. `team_ids` lists the teams the invitee joins on accepting.

{
  "invitations": [
    {
      "id": 7,
      "email": "dev@example.com",
      "role": "member",
      "token": "3f9c2a71d0b64e88a5c1f2e3d4a5b6c7",
      "status": "pending",
      "expires_at": "2025-01-27T10:00:00Z",
      "created_at": "2025-01-20T10:00:00Z",
      "team_ids": [31]
    }
  ]
}

curl https://stackness.dev/api/v1/orgs/acme/invitations \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/invitations", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Invite someone to the organization by email (owner or admin), optionally straight into some of its teams. The role defaults to member when omitted. An invitation email is sent and the invitation expires after 7 days. Fails with 409 DUPLICATE_INVITE when a pending invitation for the email already exists, 402 BILLING_REQUIRED or SEAT_LIMIT_REACHED when the organization has no free seats, and 400 VALIDATION_ERROR when a team ID belongs to another organization.

{
  "id": 7,
  "email": "dev@example.com",
  "role": "member",
  "token": "3f9c2a71d0b64e88a5c1f2e3d4a5b6c7",
  "status": "pending",
  "expires_at": "2025-01-27T10:00:00Z",
  "created_at": "2025-01-20T10:00:00Z",
  "team_ids": [31]
}

curl -X POST https://stackness.dev/api/v1/orgs/acme/invitations \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"email": "dev@example.com", "role": "member", "team_ids": [31]}'

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/invitations", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ email: "dev@example.com", role: "member", team_ids: [31] }),
});
const data = await res.json();

Cancel an organization invitation (owner or admin). The invitation is marked cancelled and can no longer be accepted. Returns 204 with no body.

204 no content

curl -X DELETE https://stackness.dev/api/v1/orgs/acme/invitations/7 \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/orgs/acme/invitations/7", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List the teams of an organization with their member counts. Members only.

{
  "teams": [
    {
      "id": 31,
      "name": "Acme Dev Team",
      "slug": "acme",
      "description": "Building the future of developer tools.",
      "member_count": 4,
      "created_at": "2025-01-20T10:00:00Z"
    }
  ]
}

curl https://stackness.dev/api/v1/orgs/acme/teams \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/teams", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Create a team inside the organization (owner or admin). The creator is not added to it. Fails with 409 TEAM_SLUG_TAKEN when the organization already has a team with that slug.

{
  "id": 32,
  "name": "Design systems",
  "slug": "design-systems",
  "description": "Components and tokens for every Acme product.",
  "member_count": 0,
  "created_at": "2025-01-21T09:00:00Z"
}

curl -X POST https://stackness.dev/api/v1/orgs/acme/teams \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Design systems", "slug": "design-systems"}'

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/teams", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Design systems", slug: "design-systems" }),
});
const data = await res.json();

Get one team of the organization by its slug. Members only. Fails with 404 TEAM_NOT_FOUND when the organization has no such team.

{
  "id": 31,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "member_count": 4,
  "created_at": "2025-01-20T10:00:00Z"
}

curl https://stackness.dev/api/v1/orgs/acme/teams/acme \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/teams/acme", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Rename a team or change its description (a lead of that team, an admin or the owner). Omitted fields are left unchanged.

{
  "id": 31,
  "name": "Acme Dev Team",
  "slug": "acme",
  "description": "Building the future of developer tools.",
  "member_count": 4,
  "created_at": "2025-01-20T10:00:00Z"
}

curl -X PATCH https://stackness.dev/api/v1/orgs/acme/teams/acme \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{"description": "Building the future of developer tools."}'

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/teams/acme", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ description: "Building the future of developer tools." }),
});
const data = await res.json();

Delete a team and its memberships (owner or admin). The people stay in the organization. Returns 204 with no body.

204 no content

curl -X DELETE https://stackness.dev/api/v1/orgs/acme/teams/acme \
  -H "Authorization: Bearer <token>"

await fetch("https://stackness.dev/api/v1/orgs/acme/teams/acme", {
  method: "DELETE",
  headers: { Authorization: `Bearer ${token}` },
});

List the members of a team with their team roles, lead or member. Members of the organization only. Offset-paginated: the page size defaults to 50 and is capped at 100. The `id` of each entry is the team membership ID.

{
  "members": [
    {
      "id": 21,
      "user_id": 42,
      "username": "sarah_chen",
      "display_name": "Sarah Chen",
      "avatar_url": "https://cdn.stackness.dev/avatars/sarah.png",
      "role": "lead"
    }
  ],
  "total_count": 4,
  "has_more": false
}

curl https://stackness.dev/api/v1/orgs/acme/teams/acme/members \
  -H "Authorization: Bearer <token>"

const res = await fetch("https://stackness.dev/api/v1/orgs/acme/teams/acme/members", {
  headers: { Authorization: `Bearer ${token}` },
});
const data = await res.json();

Add an organization member to a team (a lead of that team, an admin or the owner). The role defaults to member. Fails with 400 NOT_ORG_MEMBER when the user is not in the organization, and 409 ALREADY_MEMBER when they are already in the team.