Goalkeeper Docs
API Reference

Goalkeeper API

Public REST API.

get/health

Get 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/session

Get the current session

Returns the authenticated user for the current session.

Responses

200The current authenticated session.
application/json · AuthSession
401The request is not authenticated.
application/json · Error
get/v1/auth/config

Get authentication configuration

Returns the authentication method configured for this service.

Responses

200Authentication configuration.
application/json · AuthConfiguration
get/v1/auth/login

Begin login

Starts the configured login flow and redirects the browser.

Parameters

returnToquery · string (uri) · optional

Same-origin application URL to open after login.

Responses

302Continue the login flow.
post/v1/auth/login

Sign in with email

Authenticates a verified email principal and starts a session.

Request body

application/json · EmailLoginRequest · required

Responses

200The session started.
application/json · AuthTransitionResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The request origin is not allowed.
application/json · Error
post/v1/auth/register

Register with email

Creates an email principal and sends a verification link.

Request body

application/json · EmailRegistrationRequest · required

Responses

202Email verification is required.
application/json · EmailRegistrationResponse
400The registration request is invalid.
application/json · Error
403The request origin is not allowed.
application/json · Error
post/v1/auth/verify-email

Verify an email principal

Consumes a single-use verification token after explicit browser confirmation.

Request body

application/json · EmailVerificationRequest · required

Responses

200The email principal was verified.
application/json · AuthTransitionResponse
400The verification token is invalid or expired.
application/json · Error
403The request origin is not allowed.
application/json · Error
get/v1/auth/callback

Complete login

Completes the configured login flow and redirects the browser.

Parameters

returnToquery · string (uri) · optional

Same-origin application URL to open after login.

Responses

302Open the authenticated application page.
post/v1/auth/logout

Log out

Ends the current session and returns the next browser location.

Responses

200The session ended.
application/json · AuthTransitionResponse
403The request origin is not allowed.
application/json · Error
get/v1/organizations

List 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 · OrganizationContext
401The request is not authenticated.
application/json · Error
post/v1/organizations

Create an organization

Creates an organization owned by the current user and makes it active.

Request body

application/json · CreateOrganizationRequest · required

Responses

201The created organization is active.
application/json · OrganizationContext
400The organization request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The request origin is not allowed.
application/json · Error
post/v1/organizations/switch

Switch organizations

Makes one of the current user's organization memberships active.

Request body

application/json · SwitchOrganizationRequest · required

Responses

200The selected organization is active.
application/json · OrganizationContext
400The organization identifier is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The user is not a member or the origin is not allowed.
application/json · Error
patch/v1/organizations/current

Update the active organization

Updates the active organization. The current user must be an owner or administrator.

Request body

application/json · UpdateOrganizationRequest · required

Responses

200The active organization was updated.
application/json · OrganizationContext
400The organization request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403Administrator access is required or the origin is not allowed.
application/json · Error
get/v1/organizations/current/members

List active organization members

Lists the user-to-organization memberships for the active organization.

Responses

200Active organization members.
application/json · ListOrganizationMembersResponse
401The request is not authenticated.
application/json · Error
403Organization membership is required.
application/json · Error
patch/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 · required

Request body

application/json · UpdateOrganizationMemberRoleRequest · required

Responses

200The membership role was updated.
application/json · UpdateOrganizationMemberRoleResponse
400The member or role is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403Administrator access is required, the owner role is immutable, or the origin is not allowed.
application/json · Error
get/v1/api-tokens

List API tokens

Lists active, unexpired API tokens for the current user and active organization.

Responses

200Active API tokens.
application/json · ListApiTokensResponse
401The request is not authenticated.
application/json · Error
post/v1/api-tokens

Create an API token

Creates a scoped API token in the active organization and returns its secret once.

Request body

application/json · CreateApiTokenRequest · required

Responses

201The token and its one-time secret.
application/json · CreateApiTokenResponse
400The token request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The request origin is not allowed.
application/json · Error
get/v1/api-token-scopes

List API token scopes

Returns the canonical API token scope registry.

Responses

200Available API token scopes and defaults.
application/json · ListApiTokenScopesResponse
delete/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) · required

API token identifier.

Responses

200The revoked API token.
application/json · RevokeApiTokenResponse
401The request is not authenticated.
application/json · Error
403The request origin is not allowed.
application/json · Error
404The API token does not exist for the current user and active organization.
application/json · Error
get/v1/goals

List goals

Lists goals in the credential's organization, constrained by its own-goals or all-goals scope.

Parameters

statusquery · GoalStatus · optional
ownerUserIdquery · string · optional
labelIdquery · string (uuid) · optional

Responses

200Goals visible to the caller.
application/json · ListGoalsResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
post/v1/goals

Create a goal

Creates an active goal. The owner defaults to the caller and the title defaults to a concise form of the detailed description.

Request body

application/json · CreateGoalRequest · required

Responses

201The created goal.
application/json · GoalResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
get/v1/goals/{goalId}

Get a goal

Parameters

goalIdpath · string (uuid) · required

Responses

200The goal.
application/json · GoalResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
patch/v1/goals/{goalId}

Update goal metadata

Updates descriptive metadata. Report a goal update to change lifecycle status.

Parameters

goalIdpath · string (uuid) · required

Request body

application/json · UpdateGoalRequest · required

Responses

200The updated goal.
application/json · GoalResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
get/v1/goals/{goalId}/updates

List goal updates

Returns the append-only status history for a goal in revision order.

Parameters

goalIdpath · string (uuid) · required

Responses

200The goal's status history.
application/json · ListGoalUpdatesResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
post/v1/goals/{goalId}/updates

Report a goal update

Appends a status report and advances the goal's current status and revision atomically.

Parameters

goalIdpath · string (uuid) · required

Request body

application/json · CreateGoalUpdateRequest · required

Responses

201The appended goal update.
application/json · GoalUpdateResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
get/v1/goal-labels

List goal labels

Responses

200Goal labels in the credential's organization.
application/json · ListGoalLabelsResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
post/v1/goal-labels

Create a goal label

Request body

application/json · CreateGoalLabelRequest · required

Responses

201The created goal label.
application/json · GoalLabelResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
get/v1/goal-labels/{labelId}

Get a goal label

Parameters

labelIdpath · string (uuid) · required

Responses

200The goal label.
application/json · GoalLabelResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
patch/v1/goal-labels/{labelId}

Update a goal label

Parameters

labelIdpath · string (uuid) · required

Request body

application/json · UpdateGoalLabelRequest · required

Responses

200The updated goal label.
application/json · GoalLabelResponse
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error
delete/v1/goal-labels/{labelId}

Delete an unused goal label

Parameters

labelIdpath · string (uuid) · required

Responses

204The goal label was deleted.
400The request is invalid.
application/json · Error
401The request is not authenticated.
application/json · Error
403The credential lacks the required scope or authority.
application/json · Error
404The resource was not found or is not visible to the caller.
application/json · Error
409The requested state conflicts with an existing resource.
application/json · Error

Releases

Versioning, published artifacts, and operator verification.