API Reference
Goalkeeper API
Public REST API.
get
/healthGet REST API health
Returns the REST API service status.
Responses
200REST API status response.application/json · service: "api" (required), status: "ok" (required)get
/v1/auth/sessionGet the current session
Returns the authenticated user for the current session.
Responses
200The current authenticated session.application/json · AuthSession401The request is not authenticated.application/json · Errorget
/v1/auth/configGet authentication configuration
Returns the authentication method configured for this service.
Responses
200Authentication configuration.application/json · AuthConfigurationget
/v1/auth/loginBegin login
Starts the configured login flow and redirects the browser.
Parameters
returnToquery · string (uri) · optionalSame-origin application URL to open after login.
Responses
302Continue the login flow.post
/v1/auth/loginSign in with email
Authenticates a verified email principal and starts a session.
Request body
application/json · EmailLoginRequest · requiredResponses
200The session started.application/json · AuthTransitionResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The request origin is not allowed.application/json · Errorpost
/v1/auth/registerRegister with email
Creates an email principal and sends a verification link.
Request body
application/json · EmailRegistrationRequest · requiredResponses
202Email verification is required.application/json · EmailRegistrationResponse400The registration request is invalid.application/json · Error403The request origin is not allowed.application/json · Errorpost
/v1/auth/verify-emailVerify an email principal
Consumes a single-use verification token after explicit browser confirmation.
Request body
application/json · EmailVerificationRequest · requiredResponses
200The email principal was verified.application/json · AuthTransitionResponse400The verification token is invalid or expired.application/json · Error403The request origin is not allowed.application/json · Errorget
/v1/auth/callbackComplete login
Completes the configured login flow and redirects the browser.
Parameters
returnToquery · string (uri) · optionalSame-origin application URL to open after login.
Responses
302Open the authenticated application page.post
/v1/auth/logoutLog out
Ends the current session and returns the next browser location.
Responses
200The session ended.application/json · AuthTransitionResponse403The request origin is not allowed.application/json · Errorget
/v1/organizationsList organizations
Lists the current user's organizations and active organization. Creates the user's first organization when none exists.
Responses
200Organization membership context.application/json · OrganizationContext401The request is not authenticated.application/json · Errorpost
/v1/organizationsCreate an organization
Creates an organization owned by the current user and makes it active.
Request body
application/json · CreateOrganizationRequest · requiredResponses
201The created organization is active.application/json · OrganizationContext400The organization request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The request origin is not allowed.application/json · Errorpost
/v1/organizations/switchSwitch organizations
Makes one of the current user's organization memberships active.
Request body
application/json · SwitchOrganizationRequest · requiredResponses
200The selected organization is active.application/json · OrganizationContext400The organization identifier is invalid.application/json · Error401The request is not authenticated.application/json · Error403The user is not a member or the origin is not allowed.application/json · Errorpatch
/v1/organizations/currentUpdate the active organization
Updates the active organization. The current user must be an owner or administrator.
Request body
application/json · UpdateOrganizationRequest · requiredResponses
200The active organization was updated.application/json · OrganizationContext400The organization request is invalid.application/json · Error401The request is not authenticated.application/json · Error403Administrator access is required or the origin is not allowed.application/json · Errorget
/v1/organizations/current/membersList active organization members
Lists the user-to-organization memberships for the active organization.
Responses
200Active organization members.application/json · ListOrganizationMembersResponse401The request is not authenticated.application/json · Error403Organization membership is required.application/json · Errorpatch
/v1/organizations/current/members/{userId}Update an organization member role
Updates a non-owner membership role. The current user must be an owner or administrator.
Parameters
userIdpath · string · requiredRequest body
application/json · UpdateOrganizationMemberRoleRequest · requiredResponses
200The membership role was updated.application/json · UpdateOrganizationMemberRoleResponse400The member or role is invalid.application/json · Error401The request is not authenticated.application/json · Error403Administrator access is required, the owner role is immutable, or the origin is not allowed.application/json · Errorget
/v1/organizations/current/invitationsList pending invitations
Lists pending invitations for the active organization. Any member may read them. Invitation tokens are never returned.
Responses
200The pending invitations were listed.application/json · ListOrganizationInvitationsResponse401The request is not authenticated.application/json · Error403The user is not a member of the organization.application/json · Errorpost
/v1/organizations/current/invitationsInvite someone to the active organization
Creates an invitation for an email address. The current user must be an owner or administrator. The acceptance link is returned only in this response; it cannot be recovered later.
Request body
application/json · CreateOrganizationInvitationRequest · requiredResponses
201The invitation was created.application/json · IssuedOrganizationInvitation400The email address or role is invalid.application/json · Error401The request is not authenticated.application/json · Error403Administrator access is required or the origin is not allowed.application/json · Error409An invitation for this address is already pending.application/json · Errordelete
/v1/organizations/current/invitations/{invitationId}Revoke a pending invitation
Revokes a pending invitation. The current user must be an owner or administrator.
Parameters
invitationIdpath · string (uuid) · requiredResponses
204The invitation was revoked.400The invitation identifier is invalid.application/json · Error401The request is not authenticated.application/json · Error403Administrator access is required, the invitation is not pending, or the origin is not allowed.application/json · Errorpost
/v1/organizations/current/invitations/{invitationId}/resendReissue a pending invitation
Issues a new token for a pending invitation, invalidating the previous link and extending the expiry. Required because the plaintext token is returned only once.
Parameters
invitationIdpath · string (uuid) · requiredResponses
200The invitation was reissued with a new link.application/json · IssuedOrganizationInvitation400The invitation identifier is invalid.application/json · Error401The request is not authenticated.application/json · Error403Administrator access is required, the invitation is not pending, or the origin is not allowed.application/json · Errorpost
/v1/organizations/invitations/acceptAccept an invitation
Consumes an invitation token and joins the authenticated user to the organization, making it active. The token must have been issued to the session's verified email address.
Request body
application/json · AcceptOrganizationInvitationRequest · requiredResponses
200The invitation was accepted.application/json · AcceptOrganizationInvitationResponse400The token is malformed.application/json · Error401The request is not authenticated.application/json · Error403The invitation was issued to a different email address, or the origin is not allowed.application/json · Error404The invitation is expired, revoked, or already used.application/json · Error409The user already belongs to the organization.application/json · Errorget
/v1/api-tokensList API tokens
Lists active, unexpired API tokens for the current user and active organization.
Responses
200Active API tokens.application/json · ListApiTokensResponse401The request is not authenticated.application/json · Errorpost
/v1/api-tokensCreate an API token
Creates a scoped API token in the active organization and returns its secret once.
Request body
application/json · CreateApiTokenRequest · requiredResponses
201The token and its one-time secret.application/json · CreateApiTokenResponse400The token request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The request origin is not allowed.application/json · Errorget
/v1/api-token-scopesList API token scopes
Returns the canonical API token scope registry.
Responses
200Available API token scopes and defaults.application/json · ListApiTokenScopesResponsedelete
/v1/api-tokens/{tokenId}Revoke an API token
Immediately revokes one of the current user's API tokens in the active organization.
Parameters
tokenIdpath · string (uuid) · requiredAPI token identifier.
Responses
200The revoked API token.application/json · RevokeApiTokenResponse401The request is not authenticated.application/json · Error403The request origin is not allowed.application/json · Error404The API token does not exist for the current user and active organization.application/json · Errorget
/v1/goalsList goals
Lists goals in the credential's organization, constrained by its own-goals or all-goals scope.
Parameters
statusquery · GoalStatus · optionalhealthquery · GoalHealth · optionalownerUserIdquery · string · optionallabelIdquery · string (uuid) · optionalResponses
200Goals visible to the caller.application/json · ListGoalsResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorpost
/v1/goalsPublish a goal
Publishes a durable goal in active status. The owner defaults to the caller and the title defaults to a concise form of the detailed description.
Request body
application/json · CreateGoalRequest · requiredResponses
201The created goal.application/json · GoalResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorget
/v1/goals/{goalId}Get a goal
Parameters
goalIdpath · string (uuid) · requiredResponses
200The goal.application/json · GoalResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorpatch
/v1/goals/{goalId}Update goal metadata
Updates descriptive metadata. Report a goal update to change lifecycle status.
Parameters
goalIdpath · string (uuid) · requiredRequest body
application/json · UpdateGoalRequest · requiredResponses
200The updated goal.application/json · GoalResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errordelete
/v1/goals/{goalId}Delete a goal
Permanently deletes a goal together with its label assignments and status history.
Parameters
goalIdpath · string (uuid) · requiredResponses
204The goal was deleted.400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorget
/v1/goals/{goalId}/updatesList goal updates
Returns the append-only status history for a goal in revision order.
Parameters
goalIdpath · string (uuid) · requiredResponses
200The goal's status history.application/json · ListGoalUpdatesResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorpost
/v1/goals/{goalId}/updatesReport a goal update
Appends a status report and advances the goal's current status and revision atomically.
Parameters
goalIdpath · string (uuid) · requiredRequest body
application/json · CreateGoalUpdateRequest · requiredResponses
201The appended goal update.application/json · GoalUpdateResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorget
/v1/goal-labelsList goal labels
Responses
200Goal labels in the credential's organization.application/json · ListGoalLabelsResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorpost
/v1/goal-labelsCreate a goal label
Request body
application/json · CreateGoalLabelRequest · requiredResponses
201The created goal label.application/json · GoalLabelResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorget
/v1/goal-labels/{labelId}Get a goal label
Parameters
labelIdpath · string (uuid) · requiredResponses
200The goal label.application/json · GoalLabelResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errorpatch
/v1/goal-labels/{labelId}Update a goal label
Parameters
labelIdpath · string (uuid) · requiredRequest body
application/json · UpdateGoalLabelRequest · requiredResponses
200The updated goal label.application/json · GoalLabelResponse400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Errordelete
/v1/goal-labels/{labelId}Delete an unused goal label
Parameters
labelIdpath · string (uuid) · requiredResponses
204The goal label was deleted.400The request is invalid.application/json · Error401The request is not authenticated.application/json · Error403The credential lacks the required scope or authority.application/json · Error404The resource was not found or is not visible to the caller.application/json · Error409The requested state conflicts with an existing resource.application/json · Error