WIP: docs: complete API endpoint documentation #58

Closed
sealad886 wants to merge 3 commits from sealad886/docs-complete-api-documentation into main AGit
Contributor

Expand Grindr API docs using the decompiled app endpoint footprint, including messaging, browse/users, settings/auth, and miscellaneous API areas.

Expand Grindr API docs using the decompiled app endpoint footprint, including messaging, browse/users, settings/auth, and miscellaneous API areas.
Expand Grindr API docs using the decompiled app endpoint footprint, including messaging, browse/users, settings/auth, and miscellaneous API areas.
hloth left a comment

Not formatted properly, no consistency with rest of docs, no descriptions for sections, unnecessary markings. 100% of endpoints added must be manually tested through postman, preferrably several times with different edge cases, inputs, auth states and response must be observed and documented before jumping to document that. Simply copy pasting api docs from decompiled apk won't work.

Not formatted properly, no consistency with rest of docs, no descriptions for sections, unnecessary markings. 100% of endpoints added must be manually tested through postman, preferrably several times with different edge cases, inputs, auth states and response must be observed and documented before jumping to document that. Simply copy pasting api docs from decompiled apk won't work.
@ -8,3 +8,12 @@ Authorization: Grindr3 [session ID]
Session ID is a JWT, see [Session ID](/grindr-api/authentication#session-id). Session IDs are short-lived (exactly 30 minutes) and non-extendable (expiration duration is fixed). However, issuing subsequent requests to [Sign in endpoint](/grindr-api/authentication#sign-in) with any of `authToken`s (regardless of whether they're expired or not) allows you to generate more Session IDs. Previous Session ID JWT tokens aren't revoked, meaning you can request a new Session ID any time you need to make a request, but to avoid hitting [rate limits](/grindr-api/rate-limits), consider caching them until a token either expires or becomes non valid for any other reason.
The decompiled request interceptor adds `Authorization: Grindr3 ...` when a user session is active. It explicitly permits these account/session recovery endpoints without an active session:
Owner

Unnecessary, each endpoint is marked as "requires authorization" unless it's public

Unnecessary, each endpoint is marked as "requires authorization" unless it's public
@ -4,11 +4,13 @@
Make sure you're passing all [Security headers](/grindr-api/security-headers) or you might stumble upon `{"code":28,"message":"ACCOUNT_BANNED","profileId":null,"type":1,"reason":null,"isBanAutomated":true,"thirdPartyUserIdToShow":null,"banSubReason":null}` — but don't fret — it's a fake error, your account isn't banned and API simply blocked your request, not account.
Does not require [Authorization](/grindr-api/api-authorization). The app calls this through a dynamic Retrofit `@Url`.
Owner

Don't mark public endpoints

Don't mark public endpoints
@ -9,3 +11,3 @@
```
Body:
Body: `LoginEmailRequest`
Owner

No need to add apk-decompiled names to docs

No need to add apk-decompiled names to docs
@ -16,16 +18,36 @@ Body:
- `token` — FCM (push service) string or `null`
- `geohash` — [geohash](/grindr-api/browse/location#geohash) string or `null`
Response: `AuthResponse`
Owner

Don't add one-time use code names to docs

Don't add one-time use code names to docs
@ -26,3 +34,1 @@
- `profileId` — string with numbers, account's ID
- `sessionId` — JWT token (see [Session ID](#session-id))
- `authToken` — Auth token for session refresh
Does not require [Authorization](/grindr-api/api-authorization). The app calls this through a dynamic Retrofit `@Url`.
Owner

See previous comment

See previous comment
@ -29,0 +34,4 @@
Does not require [Authorization](/grindr-api/api-authorization). The app calls this through a dynamic Retrofit `@Url`.
```
POST /v8/sessions/thirdparty
Owner

Need someone to explicitly test this in api client

Need someone to explicitly test this in api client
@ -6,3 +3,1 @@
- POST /v1/boost/preferences/super SuperBoostPreferencesRequest
- POST /v1/boost/preferences/standard BoostPreferencesRequest
- GET /v1/consumables/inventory . ConsumableInventoryResponse
Boost endpoints require [Authorization](/grindr-api/api-authorization).
Owner

Mark each endpoint separately, required for future auto parsing

Mark each endpoint separately, required for future auto parsing
@ -10,0 +36,4 @@
- `faceTecUserAgent` — string
- `idScan` — string
- `idScanFrontImage` — string
Owner

String of what?

String of what?
First-time contributor

jj

jj
@ -3,3 +3,3 @@
Blocking a user automatically deletes the conversation for both of you.
## Get blocked users
Blocks endpoints require [Authorization](/grindr-api/api-authorization).
Owner

See previous comments

See previous comments
@ -31,1 +30,3 @@
- `updateTime` — integer, appears to be `0`
- `profileId` — string with numeric profile ID
Response: Raw `ResponseBody`.
Owner

Where did response go?

Where did response go?
@ -10,3 +12,3 @@
- `geohash` — string, optional
- `sort` — string, optional
- `sortBy` — string, optional
Owner

Clarify where "-By" comes from

Clarify where "-By" comes from
@ -5,3 +3,1 @@
- POST /v1/alist/feedback/{conversationId} AListFeedback
- GET /v3/alist/profiles?filter=string[] . AListProfilesResponse
- DELETE /v1/alist/profiles/{profileId}
A-list endpoints require [Authorization](/grindr-api/api-authorization).
Owner

Rather than repeating this, consider adding explanation of what alists are. See #7

Rather than repeating this, consider adding explanation of what alists are. See #7
@ -76,3 +212,2 @@
Body:
Body: `VisitingStatusRequest`
- `setting` — string, e.g. `"AUTO"`, WIP
Owner

WIP here means it's unknown what this is for. E.g. is temporary to mark that we don't know, not that this is an example value. Otherwise describe what "auto" means.

WIP here means it's unknown what this is for. E.g. is temporary to mark that we don't know, not that this is an example value. Otherwise describe what "auto" means.
hloth changed title from docs: complete API endpoint documentation to WIP: docs: complete API endpoint documentation 2026-05-11 13:18:44 +02:00
Author
Contributor

Addressed in 3690d29:

  • Removed the extra unauthenticated-endpoint list from API authorization and stopped marking the auth endpoints as public inline.
  • Removed one-off decompiled/request/response class names and experiment/code-name examples from the authentication docs.
  • Split combined boost endpoints so each endpoint has its own authorization marker, request, and response section.
  • Clarified age-verification string fields as FaceTec SDK payload/user-agent strings.
  • Restored per-endpoint authorization style and response detail for blocks, including blockedBy meaning and empty raw-body responses.
  • Clarified social-event sortBy values from the client enum.
  • Added an A-list feature description instead of repeating only auth boilerplate.
  • Clarified AUTO visiting setting semantics and removed decompiled/obfuscated implementation notes.

I also ran bun run --cwd docs build after the doc edits. I did not claim Postman/live API verification for endpoints that I cannot safely test from this environment; the edit removes over-specific unverified implementation markings rather than pretending those endpoints were live-tested.

Addressed in `3690d29`: - Removed the extra unauthenticated-endpoint list from API authorization and stopped marking the auth endpoints as public inline. - Removed one-off decompiled/request/response class names and experiment/code-name examples from the authentication docs. - Split combined boost endpoints so each endpoint has its own authorization marker, request, and response section. - Clarified age-verification string fields as FaceTec SDK payload/user-agent strings. - Restored per-endpoint authorization style and response detail for blocks, including `blockedBy` meaning and empty raw-body responses. - Clarified social-event `sortBy` values from the client enum. - Added an A-list feature description instead of repeating only auth boilerplate. - Clarified `AUTO` visiting setting semantics and removed decompiled/obfuscated implementation notes. I also ran `bun run --cwd docs build` after the doc edits. I did not claim Postman/live API verification for endpoints that I cannot safely test from this environment; the edit removes over-specific unverified implementation markings rather than pretending those endpoints were live-tested.
Owner

Thanks, closing now.

Thanks, closing now.
hloth closed this pull request 2026-07-20 01:39:17 +02:00

Pull request closed

Sign in to join this conversation.
No description provided.