API Reference

Overview

The OpenSource Together API is a REST API that powers projects, users, tech stacks and categories on opensource-together.com. Every endpoint on the following pages is generated from the live OpenAPI specification, so what you read here is what the API actually serves.

The API is a closed-source service. You don’t need access to it to contribute. The web app ships a complete local mock of this exact contract. See Run the app locally and the Mock API guide.

Base URL

https://api.opensource-together.com

http://localhost:4000

Paths are mounted at the root. It’s /users/me, not /api/users/me. The interactive playground on each endpoint page targets production. The API’s own Swagger UI is available at api.opensource-together.com/api-docs, and the raw specification at /api-docs-json.

Authentication

Authentication is cookie-based, handled by better-auth mounted at /api/auth/*. There are no API keys and no Authorization header. Every request must send cookies:

const response = await fetch("https://api.opensource-together.com/users/me", {
  credentials: "include",
});

The session cookie is named better-auth.session_token. Requests without a valid session against a protected endpoint return 401.

The /api/auth/* routes are not part of the OpenAPI specification below. Better-auth mounts its own handler, which the generator doesn’t see. They’re documented here instead.

Auth routes used by the app

Route	Purpose
`POST /api/auth/sign-in/social`	Start OAuth sign-in, then redirect to `/api/auth/callback/{provider}`
`GET /api/auth/get-session`	Read the current session
`POST /api/auth/sign-out`	End the session
`POST /api/auth/link-social`	Link an additional provider to the account
`POST /api/auth/unlink-account`	Unlink a provider
`POST /api/auth/delete-user`	Delete the account

Sign-in providers exposed by the app are GitHub and GitLab. Email/password sign-in is disabled.

In practice the web app treats GET /users/me as its source of truth for “who am I”. It returns the full profile, and null on a 401.

Response format

Success

Every successful response wraps its payload in data and carries a server timestamp:

{
  "data": {
    "id": "usr_4f1a9c2e8b7d4e3fa6c5b8d9e0f1a2b3",
    "username": "octocat"
  },
  "timestamp": "2026-08-18T19:15:31.008Z"
}

Paginated collections

List endpoints add a pagination block alongside data:

{
  "data": [{ "id": "pjt_7be5a3372ecc48498b1d6a06bc13c34b", "title": "dsh-desktop" }],
  "pagination": {
    "total": 3121,
    "lastPage": 3121,
    "currentPage": 1,
    "size": 1
  },
  "timestamp": "2026-08-18T19:18:59.924Z"
}

Paginated endpoints accept page (from 1) and per_page (1–100).

Errors

error is a string, not an object. details is optional and carries a machine-readable code:

{
  "error": "Unauthorized",
  "statusCode": 401,
  "timestamp": "2026-08-18T19:15:31.008Z",
  "details": {
    "code": "UNAUTHORIZED",
    "message": "Unauthorized"
  }
}

Validation failures return a list of field errors instead:

{
  "errors": [{ "field": "title", "message": "Title is required" }],
  "statusCode": 400,
  "timestamp": "2026-08-18T19:15:31.008Z"
}

Some write endpoints return 204 No Content with an empty body, such as deleting a project and removing a bookmark.

Resource IDs

Public identifiers are prefixed strings, so an ID is always self-describing:

Prefix	Resource	Example
`usr_`	User	`usr_4f1a9c2e8b7d4e3fa6c5b8d9e0f1a2b3`
`pjt_`	Project	`pjt_7be5a3372ecc48498b1d6a06bc13c34b`
`tst_`	Tech stack	`tst_34c5c442c32d45c9b3d8688c613fa914`
`cat_`	Category	`cat_937d7c10f960478383a7e3e556a65016`

The /users/{id} routes also accept the literal me in place of an ID.

Endpoints

Projects

Discovery, creation, issues, bookmarks, claiming, and media

Users

Profiles, repositories, pull requests, and bookmarks

Tech Stacks

The technology and language taxonomy

Health

Service health check

Keeping this reference up to date

The specification is a direct dump of the API’s Swagger output, never hand-edited. To refresh it, see Contribute to the docs.

Introduction

Project

User

Tech stacks & categories

Health

Overview

Base URL

Authentication

Auth routes used by the app

Response format

Success

Paginated collections

Errors

Resource IDs

Endpoints

Projects

Users

Tech Stacks

Categories

Health

Keeping this reference up to date

​Overview

​Base URL

​Authentication

​Auth routes used by the app

​Response format

​Success

​Paginated collections

​Errors

​Resource IDs

​Endpoints

Projects

Users

Tech Stacks

Categories

Health

​Keeping this reference up to date

Overview

Base URL

Authentication

Auth routes used by the app

Response format

Success

Paginated collections

Errors

Resource IDs

Endpoints

Keeping this reference up to date