devngn.ai

devngn.ai Wellness API

OpenAPI 3.1.1 · v1

Opt-in dev wellness service: profiles, goals, equipment, schedule gaps, and short activity prompts.

Authentication

Every endpoint requires a GitHub OAuth bearer token. Obtain one via the device flow (GET /v1/auth/github/device) and send it as Authorization: Bearer ….

Consent gate

Data endpoints (profile, goals, equipment, schedule, prompts) require a recorded consent record first (POST /v1/consent) or they return 403.

openapi.json Read the guide

Meta

get /v1/hello

Responses

Status Description Body
200 OK -

Auth

get /v1/auth/github/web/start

Parameters

Name In Type
returnPath query string

Responses

Status Description Body
400 Bad Request
AuthErrorResponse (application/json)
get /v1/auth/github/web/callback

Parameters

Name In Type
code query string
state query string
error query string
error_description query string

Responses

Status Description Body
200 OK
AccessTokenResponse (application/json)
400 Bad Request
AuthErrorResponse (application/json)

Profile

get /v1/profile

Responses

Status Description Body
200 OK
ProfileResponse (application/json)
404 Not Found -
delete /v1/profile

Responses

Status Description Body
204 No Content -
404 Not Found -

Goals

get /v1/goals

Responses

Status Description Body
200 OK
GoalResponse[] (application/json)
get /v1/goals/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
GoalResponse (application/json)
404 Not Found -
put /v1/goals/{id}

Parameters

Name In Type
id * path string (uuid)

Request body (required)

application/json UpdateGoalRequest

Responses

Status Description Body
200 OK
GoalResponse (application/json)
400 Bad Request
HttpValidationProblemDetails (application/problem+json)
404 Not Found -
delete /v1/goals/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
204 No Content -
404 Not Found -

Equipment

get /v1/equipment

Responses

Status Description Body
200 OK
EquipmentResponse[] (application/json)
get /v1/equipment/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
EquipmentResponse (application/json)
404 Not Found -
delete /v1/equipment/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
204 No Content -
404 Not Found -

ScheduleSources

get /v1/schedule/sources/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
ScheduleSourceResponse (application/json)
404 Not Found -
delete /v1/schedule/sources/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
204 No Content -
404 Not Found -
post /v1/schedule/sources/{id}/sync

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
ScheduleSyncResponse (application/json)
404 Not Found -
409 Conflict
ProblemDetails (application/problem+json)
422 Unprocessable Entity
ProblemDetails (application/problem+json)
503 Service Unavailable
ProblemDetails (application/problem+json)

ScheduleEvents

get /v1/schedule/events

Parameters

Name In Type
from query string (date-time)
to query string (date-time)
sourceId query string (uuid)

Responses

Status Description Body
200 OK
ScheduleEventResponse[] (application/json)
400 Bad Request
HttpValidationProblemDetails (application/problem+json)
delete /v1/schedule/events/{id}

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
204 No Content -
404 Not Found -

ScheduleConnect

get /v1/schedule/connect/google

Parameters

Name In Type
returnPath query string

Responses

Status Description Body
200 OK -
get /v1/schedule/connect/microsoft

Parameters

Name In Type
returnPath query string

Responses

Status Description Body
200 OK -
get /v1/schedule/callback/google

Parameters

Name In Type
code query string
state query string
error query string

Responses

Status Description Body
200 OK -
get /v1/schedule/callback/microsoft

Parameters

Name In Type
code query string
state query string
error query string

Responses

Status Description Body
200 OK -

Gaps

get /v1/gaps

Parameters

Name In Type
from query string (date-time)
to query string (date-time)
tz query string

Responses

Status Description Body
200 OK
GapResponse[] (application/json)
400 Bad Request
HttpValidationProblemDetails (application/problem+json)

Activities

get /v1/activities

Parameters

Name In Type
availableEquipmentTag query string[]
bodyArea query BodyArea
maxDurationSeconds query integer (int32) | string

Responses

Status Description Body
200 OK
ActivityResponse[] (application/json)
400 Bad Request
HttpValidationProblemDetails (application/problem+json)

Prompts

get /v1/prompts

Parameters

Name In Type
limit query integer (int32) | string

Responses

Status Description Body
200 OK
PromptResponse[] (application/json)
post /v1/prompts/next

Parameters

Name In Type
tz query string
channel query string

Responses

Status Description Body
200 OK
PromptResponse (application/json)
204 No Content -
400 Bad Request
HttpValidationProblemDetails (application/problem+json)
post /v1/prompts/{id}/dismiss

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
PromptResponse (application/json)
404 Not Found -
post /v1/prompts/{id}/complete

Parameters

Name In Type
id * path string (uuid)

Responses

Status Description Body
200 OK
PromptResponse (application/json)
404 Not Found -
post /v1/prompts/{id}/feedback

Parameters

Name In Type
id * path string (uuid)

Request body (required)

application/json FeedbackRequest

Responses

Status Description Body
200 OK
PromptResponse (application/json)
400 Bad Request
HttpValidationProblemDetails (application/problem+json)
404 Not Found -
get /v1/prompts/stream

Parameters

Name In Type
tz query string
channel query string

Responses

Status Description Body
200 OK -
get /v1/prompts/ws

Parameters

Name In Type
tz query string
channel query string

Responses

Status Description Body
200 OK -

Gamification

get /v1/gamification/me

Responses

Status Description Body
200 OK
PlayerStateResponse (application/json)
get /v1/gamification/badges

Responses

Status Description Body
200 OK
BadgeResponse[] (application/json)
get /v1/gamification/milestones

Responses

Status Description Body
200 OK
MilestoneResponse[] (application/json)
get /v1/gamification/leaderboard

Responses

Status Description Body
200 OK
LeaderboardEntry[] (application/json)

Social

get /v1/social/profile

Responses

Status Description Body
200 OK
SocialProfileResponse (application/json)
404 Not Found -
post /v1/social/follow/{followeeId}

Parameters

Name In Type
followeeId * path string (uuid)

Responses

Status Description Body
204 No Content -
400 Bad Request -
409 Conflict -
delete /v1/social/follow/{followeeId}

Parameters

Name In Type
followeeId * path string (uuid)

Responses

Status Description Body
204 No Content -
404 Not Found -
get /v1/social/followers

Responses

Status Description Body
200 OK
FollowerResponse[] (application/json)
get /v1/social/following

Responses

Status Description Body
200 OK
FollowResponse[] (application/json)
get /v1/social/feed

Responses

Status Description Body
200 OK
FeedItemResponse[] (application/json)

Schemas

AcceptConsentRequest

Property Type
version * string

AccessTokenResponse

Property Type
accessToken * string
tokenType * string
expiresAt * string (date-time)
user * AuthenticatedUserResponse

ActivityResponse

Property Type
id * string (uuid)
slug * string
title * string
description * string
bodyArea * BodyArea
intensity * IntensityLevel
durationSeconds * integer (int32) | string
equipmentTags * string[]
animationProvider * string
animationAssetId * string
licenseAttribution * string | null

AuthenticatedUserResponse

Property Type
id * string (uuid)
gitHubId * integer (int64) | string
login * string
displayName * string | null
avatarUrl * string | null

AuthErrorResponse

Property Type
error * string
description string | null

BadgeResponse

Property Type
key * string
name * string
description * string
icon * string
category * string
isHidden * boolean
earned * boolean
earnedAt * string | null

BodyArea

FullUpperLowerCoreNeckBackWristsHipsAnklesBreathPosture

ConsentSnapshot

Property Type
version * string
text * string
acceptedAt * string (date-time)

ConsentStateResponse

Property Type
accepted * null | ConsentSnapshot
current * CurrentConsentText

CreateEquipmentRequest

Property Type
tag * string
displayName * string
notes string | null

CreateGoalRequest

Property Type
title * string
description string | null
category GoalCategory
targetMetric string | null
startDate * string (date)
endDate string | null

CreateScheduleSourceRequest

Property Type
type * ScheduleSourceType
displayName * string

CurrentConsentText

Property Type
version * string
text * string

DeliveryChannel

VscodeCliWeb

DeviceFlowPollRequest

Property Type
sessionId * string

DeviceFlowStartResponse

Property Type
sessionId * string
userCode * string
verificationUri * string
expiresInSeconds * integer (int32) | string
intervalSeconds * integer (int32) | string

EquipmentResponse

Property Type
id * string (uuid)
tag * string
displayName * string
notes * string | null
createdAt * string (date-time)

FeedbackRequest

Property Type
rating integer (int16) | string

FeedItemResponse

Property Type
id * string (uuid)
type * FeedItemType
message * string
createdAt * string (date-time)

FeedItemType

PromptCompletedBadgeEarnedMilestoneAchievedLevelUpGoalCreatedFollowed

FitnessBaseline

UnspecifiedSedentaryLightModerateActive

FollowerResponse

Property Type
followerId * string (uuid)
followedAt * string (date-time)

FollowResponse

Property Type
followeeId * string (uuid)
followedAt * string (date-time)

GapResponse

Property Type
startUtc * string (date-time)
endUtc * string (date-time)
durationMinutes * integer (int32) | string

GoalCategory

MobilityStrengthBreathingPostureCardioLight

GoalResponse

Property Type
id * string (uuid)
title * string
description * string | null
category * GoalCategory
targetMetric * string | null
startDate * string (date)
endDate * string | null
createdAt * string (date-time)
updatedAt * string (date-time)

HttpValidationProblemDetails

Property Type
type string | null
title string | null
status integer | string | null
detail string | null
instance string | null
errors object

IntensityLevel

LowMediumHigh

LeaderboardEntry

Property Type
userId * string (uuid)
displayName * string
totalXp * integer (int32) | string
level * integer (int32) | string
rankTier * RankTier

MilestoneResponse

Property Type
key * string
name * string
description * string
isHidden * boolean
achieved * boolean
achievedAt * string | null

PlayerStateResponse

Property Type
level * integer (int32) | string
totalXp * integer (int32) | string
xpIntoLevel * integer (int32) | string
xpForNextLevel * integer (int32) | string
currentStreak * integer (int32) | string
longestStreak * integer (int32) | string
rankTier * RankTier

ProblemDetails

Property Type
type string | null
title string | null
status integer | string | null
detail string | null
instance string | null

ProfileResponse

Property Type
id * string (uuid)
ageRange * string | null
heightCm * number | string | null
weightKg * number | string | null
fitnessBaseline * FitnessBaseline
preferredIntensity * IntensityLevel
limitations * string | null
timeOfDayPreference * string | null
updatedAt * string (date-time)

PromptResponse

Property Type
id * string (uuid)
activityId * string (uuid)
activitySlug * string
activityTitle * string
activityDescription * string
bodyArea * BodyArea
intensity * IntensityLevel
durationSeconds * integer (int32) | string
equipmentTags * string[]
animationProvider * string
animationAssetId * string
licenseAttribution * string | null
gapStartUtc * string (date-time)
gapEndUtc * string (date-time)
deliveredAt * string (date-time)
deliveredVia * DeliveryChannel
dismissedAt * string | null
completedAt * string | null
feedbackRating * integer | string | null

PushScheduleEventItem

Property Type
externalId * string
startUtc * string (date-time)
endUtc * string (date-time)
busy boolean

PushScheduleEventsRequest

Property Type
sourceId * string (uuid)
items * PushScheduleEventItem[]

RankTier

BronzeSilverGoldPlatinumDiamondLegend

ScheduleEventResponse

Property Type
id * string (uuid)
sourceId * string (uuid)
externalId * string | null
startUtc * string (date-time)
endUtc * string (date-time)
busy * boolean

ScheduleSourceConnectionStatus

ConnectedNeedsReconnectDisabledErrorPendingConnection

ScheduleSourceResponse

Property Type
id * string (uuid)
type * ScheduleSourceType
displayName * string
connectionStatus * ScheduleSourceConnectionStatus
scope * string | null
lastSyncAt * string | null
lastRefreshAt * string | null
lastSyncErrorCode * string | null
lastSyncErrorAt * string | null
createdAt * string (date-time)

ScheduleSourceType

UserGoogleMicrosoft

ScheduleSyncResponse

Property Type
synced * integer (int32) | string

SocialProfileResponse

Property Type
userId * string (uuid)
displayName * string
bio * string | null
isPublic * boolean

UpdateEquipmentRequest

Property Type
displayName * string
notes string | null

UpdateGoalRequest

Property Type
title * string
description string | null
category GoalCategory
targetMetric string | null
startDate * string (date)
endDate string | null

UpdateScheduleSourceRequest

Property Type
displayName string | null
connectionStatus null | ScheduleSourceConnectionStatus

UpsertProfileRequest

Property Type
ageRange string | null
heightCm number | string | null
weightKg number | string | null
fitnessBaseline FitnessBaseline
preferredIntensity IntensityLevel
limitations string | null
timeOfDayPreference string | null

UpsertSocialProfileRequest

Property Type
displayName * string
bio string | null
isPublic boolean