Poggio Labs
Goalkeeper API

Open-source (Apache-2.0) REST API for Goalkeeper, Poggio Labs' durable-goals record for teams of people and AI agents. 36 operations across goals, append-only goal updates, labels, organizations, API tokens and authentication, described by a published OpenAPI 3.1.0 document. Self-hosted: Poggio Labs runs no hosted instance, so the only declared server is the local development host and operators supply their own. Writes are idempotency-keyed and revision-checked.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.1.0",
  "info": {
    "title": "Goalkeeper API",
    "version": "0.0.0",
    "description": "Public REST API."
  },
  "servers": [
    {
      "url": "http://localhost:3001",
      "description": "Local development"
    }
  ],
  "tags": [
    {
      "name": "System",
      "description": "Service status endpoints."
    },
    {
      "name": "Authentication",
      "description": "User session lifecycle."
    },
    {
      "name": "Organizations",
      "description": "Organization membership and active organization selection."
    },
    {
      "name": "API Tokens",
      "description": "Scoped credentials owned by an organization and user."
    },
    {
      "name": "Goals",
      "description": "Organization goals and their label taxonomy."
    }
  ],
  "paths": {
    "/health": {
      "get": {
        "operationId": "getApiHealth",
        "summary": "Get REST API health",
        "description": "Returns the REST API service status.",
        "tags": [
          "System"
        ],
        "responses": {
          "200": {
            "description": "REST API status response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "service",
                    "status"
                  ],
                  "properties": {
                    "service": {
                      "type": "string",
                      "const": "api"
                    },
                    "status": {
                      "type": "string",
                      "const": "ok"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/session": {
      "get": {
        "operationId": "getAuthSession",
        "summary": "Get the current session",
        "description": "Returns the authenticated user for the current session.",
        "tags": [
          "Authentication"
        ],
        "responses": {
          "200": {
            "description": "The current authenticated session.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/config": {
      "get": {
        "operationId": "getAuthConfiguration",
        "summary": "Get authentication configuration",
        "description": "Returns the authentication method configured for this service.",
        "tags": [
          "Authentication"
        ],
        "responses": {
          "200": {
            "description": "Authentication configuration.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthConfiguration"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/login": {
      "get": {
        "operationId": "beginAuthLogin",
        "summary": "Begin login",
        "description": "Starts the configured login flow and redirects the browser.",
        "tags": [
          "Authentication"
        ],
        "parameters": [
          {
            "name": "returnTo",
            "in": "query",
            "required": false,
            "description": "Same-origin application URL to open after login.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Continue the login flow.",
            "headers": {
              "Location": {
                "description": "The next browser location.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "loginWithEmail",
        "summary": "Sign in with email",
        "description": "Authenticates a verified email principal and starts a session.",
        "tags": [
          "Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailLoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The session started.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTransitionResponse"
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/register": {
      "post": {
        "operationId": "registerWithEmail",
        "summary": "Register with email",
        "description": "Creates an email principal and sends a verification link.",
        "tags": [
          "Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailRegistrationRequest"
              }
            }
          }
        },
        "responses": {
          "202": {
            "description": "Email verification is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EmailRegistrationResponse"
                }
              }
            }
          },
          "400": {
            "description": "The registration request is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/verify-email": {
      "post": {
        "operationId": "verifyEmail",
        "summary": "Verify an email principal",
        "description": "Consumes a single-use verification token after explicit browser confirmation.",
        "tags": [
          "Authentication"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailVerificationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The email principal was verified.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTransitionResponse"
                }
              }
            }
          },
          "400": {
            "description": "The verification token is invalid or expired.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/callback": {
      "get": {
        "operationId": "completeAuthLogin",
        "summary": "Complete login",
        "description": "Completes the configured login flow and redirects the browser.",
        "tags": [
          "Authentication"
        ],
        "parameters": [
          {
            "name": "returnTo",
            "in": "query",
            "required": false,
            "description": "Same-origin application URL to open after login.",
            "schema": {
              "type": "string",
              "format": "uri"
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Open the authenticated application page.",
            "headers": {
              "Location": {
                "description": "The authenticated application location.",
                "schema": {
                  "type": "string",
                  "format": "uri"
                }
              }
            }
          }
        }
      }
    },
    "/v1/auth/logout": {
      "post": {
        "operationId": "logoutAuthSession",
        "summary": "Log out",
        "description": "Ends the current session and returns the next browser location.",
        "tags": [
          "Authentication"
        ],
        "responses": {
          "200": {
            "description": "The session ended.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthTransitionResponse"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations": {
      "get": {
        "operationId": "listOrganizations",
        "summary": "List organizations",
        "description": "Lists the current user's organizations and active organization. Creates the user's first organization when none exists.",
        "tags": [
          "Organizations"
        ],
        "responses": {
          "200": {
            "description": "Organization membership context.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationContext"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createOrganization",
        "summary": "Create an organization",
        "description": "Creates an organization owned by the current user and makes it active.",
        "tags": [
          "Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrganizationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The created organization is active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationContext"
                }
              }
            }
          },
          "400": {
            "description": "The organization request is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/switch": {
      "post": {
        "operationId": "switchOrganization",
        "summary": "Switch organizations",
        "description": "Makes one of the current user's organization memberships active.",
        "tags": [
          "Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SwitchOrganizationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The selected organization is active.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationContext"
                }
              }
            }
          },
          "400": {
            "description": "The organization identifier is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The user is not a member or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current": {
      "patch": {
        "operationId": "updateCurrentOrganization",
        "summary": "Update the active organization",
        "description": "Updates the active organization. The current user must be an owner or administrator.",
        "tags": [
          "Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOrganizationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The active organization was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationContext"
                }
              }
            }
          },
          "400": {
            "description": "The organization request is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Administrator access is required or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current/members": {
      "get": {
        "operationId": "listCurrentOrganizationMembers",
        "summary": "List active organization members",
        "description": "Lists the user-to-organization memberships for the active organization.",
        "tags": [
          "Organizations"
        ],
        "responses": {
          "200": {
            "description": "Active organization members.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListOrganizationMembersResponse"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Organization membership is required.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current/members/{userId}": {
      "patch": {
        "operationId": "updateCurrentOrganizationMemberRole",
        "summary": "Update an organization member role",
        "description": "Updates a non-owner membership role. The current user must be an owner or administrator.",
        "tags": [
          "Organizations"
        ],
        "parameters": [
          {
            "name": "userId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOrganizationMemberRoleRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The membership role was updated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpdateOrganizationMemberRoleResponse"
                }
              }
            }
          },
          "400": {
            "description": "The member or role is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Administrator access is required, the owner role is immutable, or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current/invitations": {
      "get": {
        "operationId": "listCurrentOrganizationInvitations",
        "summary": "List pending invitations",
        "description": "Lists pending invitations for the active organization. Any member may read them. Invitation tokens are never returned.",
        "tags": [
          "Organizations"
        ],
        "responses": {
          "200": {
            "description": "The pending invitations were listed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListOrganizationInvitationsResponse"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The user is not a member of the organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createCurrentOrganizationInvitation",
        "summary": "Invite someone to the active organization",
        "description": "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.",
        "tags": [
          "Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrganizationInvitationRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The invitation was created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuedOrganizationInvitation"
                }
              }
            }
          },
          "400": {
            "description": "The email address or role is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Administrator access is required or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "An invitation for this address is already pending.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current/invitations/{invitationId}": {
      "delete": {
        "operationId": "revokeCurrentOrganizationInvitation",
        "summary": "Revoke a pending invitation",
        "description": "Revokes a pending invitation. The current user must be an owner or administrator.",
        "tags": [
          "Organizations"
        ],
        "parameters": [
          {
            "name": "invitationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "The invitation was revoked."
          },
          "400": {
            "description": "The invitation identifier is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Administrator access is required, the invitation is not pending, or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/current/invitations/{invitationId}/resend": {
      "post": {
        "operationId": "resendCurrentOrganizationInvitation",
        "summary": "Reissue a pending invitation",
        "description": "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.",
        "tags": [
          "Organizations"
        ],
        "parameters": [
          {
            "name": "invitationId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The invitation was reissued with a new link.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IssuedOrganizationInvitation"
                }
              }
            }
          },
          "400": {
            "description": "The invitation identifier is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Administrator access is required, the invitation is not pending, or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/organizations/invitations/accept": {
      "post": {
        "operationId": "acceptOrganizationInvitation",
        "summary": "Accept an invitation",
        "description": "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.",
        "tags": [
          "Organizations"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptOrganizationInvitationRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The invitation was accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AcceptOrganizationInvitationResponse"
                }
              }
            }
          },
          "400": {
            "description": "The token is malformed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The invitation was issued to a different email address, or the origin is not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "The invitation is expired, revoked, or already used.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "The user already belongs to the organization.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/v1/api-tokens": {
      "get": {
        "operationId": "listApiTokens",
        "summary": "List API tokens",
        "description": "Lists active, unexpired API tokens for the current user and active organization.",
        "tags": [
          "API Tokens"
        ],
        "responses": {
          "200": {
            "description": "Active API tokens.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ListApiTokensResponse"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createApiToken",
        "summary": "Create an API token",
        "description": "Creates a scoped API token in the active organization and returns its secret once.",
        "tags": [
          "API Tokens"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateApiTokenRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The token and its one-time secret.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CreateApiTokenResponse"
                }
              }
            }
          },
          "400": {
            "description": "The token request is invalid.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "The request is not authenticated.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "The request origin is not allowed.

# --- truncated at 32 KB (99 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/poggio-labs/refs/heads/main/openapi/poggio-labs-goalkeeper-openapi.json
Goalkeeper API

Documentation

Specifications

Other Resources

OpenAPI Specification
