Sageox Miscellaneous API

openapi: 3.2.0
info:
  title: SageOx Miscellaneous API
  version: 1.0.0
  description: '# API Reference


    ## Overview


    SageOx is a platform that captures team knowledge from discussions, decisions, and work context into a Ledger (per-repo historical record) and Team Context (team-wide shared knowledge).'
  contact:
    name: SageOx Team
  license:
    name: MIT
servers:
- url: http://localhost:3000
  description: Devcontainer
- url: https://test.sageox.ai
  description: Test
- url: https://sageox.ai
  description: Production
security:
- bearerAuth: []
tags:
- name: Miscellaneous
paths:
  /api/v1/config/features:
    get:
      operationId: getConfigFeatures
      summary: Get platform feature flags
      description: 'Returns platform-level feature flags that determine which features are enabled/disabled.

        Used by frontend and clients to conditionally render UI, show settings, or enable features.


        **Feature flags:**

        - **photos:** Photo/media features enabled

        - **notifications:** Notification delivery channels configuration


        For user-targeted feature flags via PostHog, use the frontend SDK with user context.


        **Authentication:** Not required (public endpoint)

        **Rate limit:** Standard rate limiting applies'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: Feature flags retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                - photos
                - notifications
                properties:
                  photos:
                    type: boolean
                    description: Photo/media features enabled
                    example: true
                  notifications:
                    type: object
                    description: Notification channel configuration
                    properties:
                      email:
                        type: boolean
                        example: true
                      push:
                        type: boolean
                        example: true
                      sms:
                        type: boolean
                        example: false
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/signing-keys:
    get:
      operationId: getSigningKeys
      summary: Get signing keys (JWKS format)
      description: 'Returns the global SageOx signing keys in JWKS (JSON Web Key Set) format per RFC 7517.

        Used to verify signatures on SAGEOX.md files and other signed artifacts.


        **Format:** JWKS-style response with Ed25519 public keys

        **Key type:** OKP (Octet Key Pair) with Ed25519 curve

        **Algorithm:** EdDSA


        **Caching:**

        - Fresh for 10 hours (max-age=36000)

        - Serve stale up to 7 days while revalidating in background

        - CDN-safe with public Cache-Control header


        **Authentication:** Not required (public endpoint)

        **Rate limit:** 30 requests/minute per IP (prevents key enumeration)


        **Note:** In the team-only model, organization-specific signing keys have been removed.

        All signatures use the global SageOx signing key.'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: Signing keys retrieved (JWKS format)
          headers:
            Cache-Control:
              schema:
                type: string
              description: Caching directive for CDN and browsers
              example: public, max-age=36000, stale-while-revalidate=604800
          content:
            application/json:
              schema:
                type: object
                required:
                - keys
                properties:
                  keys:
                    type: array
                    description: Array of JSON Web Keys
                    items:
                      type: object
                      required:
                      - kid
                      - kty
                      - alg
                      - crv
                      - x
                      - use
                      properties:
                        kid:
                          type: string
                          description: Key ID (matches public_key_id in signature blocks)
                          example: sageox-key-2025-01
                        kty:
                          type: string
                          description: Key type (OKP for Octet Key Pair)
                          enum:
                          - OKP
                          example: OKP
                        alg:
                          type: string
                          description: Signature algorithm
                          enum:
                          - EdDSA
                          example: EdDSA
                        crv:
                          type: string
                          description: Elliptic curve
                          enum:
                          - Ed25519
                          example: Ed25519
                        x:
                          type: string
                          description: Base64url-encoded public key (32 bytes for Ed25519 = 43 chars)
                          example: abcdefghijklmnopqrstuvwxyz0123456789ABCD
                        use:
                          type: string
                          description: Key use (sig for signatures)
                          enum:
                          - sig
                          example: sig
              examples:
                with_keys:
                  value:
                    keys:
                    - kid: sageox-key-2025-01
                      kty: OKP
                      alg: EdDSA
                      crv: Ed25519
                      x: abcdefghijklmnopqrstuvwxyz0123456789ABCD
                      use: sig
                no_keys:
                  value:
                    keys: []
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/update:
    get:
      operationId: getSignedUpdate
      summary: Get signed SAGEOX.md update
      description: 'Returns the signed SAGEOX.md file (team conventions) for the authenticated user.

        The response includes content and cryptographic signature for verification.


        **Signature format:** EdDSA signature using the global SageOx signing key

        **Verification:** Use /api/v1/signing-keys to get public key for verification


        **Parameters:**

        - **team_id** (optional): Specific team''s SAGEOX.md. If not provided, returns default/merged content.


        **Authorization:** User must be member of requested team (if team_id specified)


        **Authentication:** Bearer token required'
      tags:
      - Miscellaneous
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: team_id
        schema:
          type: string
          pattern: ^team_
          example: team_abc123xyz
        description: Optional team ID to get team-specific SAGEOX.md
      responses:
        '200':
          description: Signed SAGEOX.md content
          content:
            application/json:
              schema:
                type: object
                required:
                - content
                - signature
                properties:
                  content:
                    type: string
                    description: SAGEOX.md file content (markdown)
                    example: '# SAGEOX.md\n\nTeam conventions and standards...'
                  signature:
                    type: object
                    description: Cryptographic signature metadata
                    properties:
                      value:
                        type: string
                        description: EdDSA signature (base64url-encoded)
                        example: abcdefgh...
                      algorithm:
                        type: string
                        description: Signing algorithm used
                        enum:
                        - EdDSA
                        example: EdDSA
                      public_key_id:
                        type: string
                        description: Key ID used to create signature (matches JWKS kid)
                        example: sageox-key-2025-01
                  team_id:
                    type: string
                    description: Team ID if team-specific content (null for default)
                    nullable: true
                    example: team_abc123xyz
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Unauthorized - user not member of requested team
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/search/entities:
    get:
      operationId: searchEntities
      summary: Search user's entities
      description: 'Full-text search across user''s entities (repositories, teams, etc.).

        Returns matching entities with metadata.


        **Query parameter:** `q` - search query string (required)

        **Type parameter:** `type` - optional filter by entity type


        **Supported entity types:**

        - `repo` - repositories

        - `team` - teams

        - `user` - users (limited visibility)


        **Authentication:** Bearer token required'
      tags:
      - Miscellaneous
      security:
      - BearerAuth: []
      parameters:
      - in: query
        name: q
        required: true
        schema:
          type: string
          minLength: 1
        description: Search query string
        example: my-project
      - in: query
        name: type
        schema:
          type: string
          enum:
          - repo
          - team
          - user
        description: Optional entity type filter
        example: repo
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                type: object
                properties:
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        type:
                          type: string
                          enum:
                          - repo
                          - team
                          - user
                          example: repo
                        id:
                          type: string
                          example: repo_01934f5a-8b9c-7def-b012-3456789abcde
                        name:
                          type: string
                          example: my-project
                        description:
                          type: string
                          nullable: true
                          example: Production repository
                        score:
                          type: number
                          description: Relevance score for sorting
                          example: 0.95
        '400':
          description: Invalid search query
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/newsletter:
    post:
      operationId: subscribeNewsletter
      summary: Subscribe to newsletter
      description: 'Subscribes an email address to the product newsletter.

        Syncs to MailerLite if configured.


        **Rate limit:** Standard rate limiting

        **Duplicate handling:** Idempotent - returns success for existing subscriptions


        **Authentication:** Not required (public endpoint)'
      tags:
      - Miscellaneous
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to subscribe
                  example: user@example.com
      responses:
        '200':
          description: Newsletter subscription processed
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    example: true
                  message:
                    type: string
                    example: Subscription successful
        '400':
          description: Invalid email address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/gitlab/pat:
    get:
      operationId: getGitLabPAT
      summary: Get GitLab personal access token
      description: 'Returns the authenticated user''s GitLab personal access token.

        Used by CLI and integrations to authenticate with GitLab API.


        **Security:** Token is sensitive - only returned to authenticated user

        **Token type:** GitLab PAT (personal access token)

        **Scopes:** api, read_repository, write_repository


        **Authentication:** Bearer token required'
      tags:
      - Miscellaneous
      security:
      - BearerAuth: []
      responses:
        '200':
          description: GitLab PAT retrieved
          content:
            application/json:
              schema:
                type: object
                required:
                - token
                properties:
                  token:
                    type: string
                    description: GitLab personal access token
                    example: glpat-abc123xyz...
                  expires_at:
                    type: string
                    format: date-time
                    description: Token expiration timestamp (null if no expiry)
                    nullable: true
                    example: '2026-12-18T10:30:00Z'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: GitLab token not configured for user
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /docs:
    get:
      operationId: getApiDocs
      summary: Get API documentation UI
      description: 'Returns interactive API documentation (Swagger/OpenAPI UI).

        Serves the SwaggerUI interface for exploring the API.


        **Authentication:** Not required (public endpoint)'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: API documentation HTML page
          content:
            text/html:
              schema:
                type: string
  /docs/openapi.json:
    get:
      operationId: getOpenAPISpec
      summary: Get OpenAPI specification
      description: 'Returns the complete OpenAPI 3.1.0 specification for the API.

        Used by code generation tools, API clients, and documentation generators.


        **Format:** OpenAPI 3.1.0 (JSON)

        **Caching:** Safe to cache and serve from CDN


        **Authentication:** Not required (public endpoint)'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: OpenAPI specification
          content:
            application/json:
              schema:
                type: object
  /avatars/{id}:
    get:
      operationId: getAvatar
      summary: Generate identicon avatar
      description: 'Generates a deterministic identicon avatar (visual hash) for a given ID.

        Useful for displaying unique visual identifiers for users, teams, or repos.


        **SVG generation:** Seedable random vector art based on ID hash

        **Deterministic:** Same ID always generates same avatar

        **Caching:** Safe to cache indefinitely (content-addressed)


        **Format negotiation:**

        - `Accept: image/svg+xml` → SVG (default, lightweight)

        - `Accept: image/png` → PNG (rasterized, if supported)


        **Authentication:** Not required (public endpoint)

        **Rate limit:** Standard rate limiting'
      tags:
      - Miscellaneous
      security: []
      parameters:
      - in: path
        name: id
        required: true
        schema:
          type: string
        description: ID to generate avatar for (user_id, team_id, repo_id, etc.)
        example: usr_01aq5p00aq5p00aq5p
      - in: header
        name: Accept
        schema:
          type: string
          enum:
          - image/svg+xml
          - image/png
        description: Desired image format
        example: image/svg+xml
      responses:
        '200':
          description: Generated identicon avatar
          content:
            image/svg+xml:
              schema:
                type: string
                format: binary
            image/png:
              schema:
                type: string
                format: binary
        '400':
          description: Invalid ID format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /metrics:
    get:
      operationId: getPrometheusMetrics
      summary: Get Prometheus metrics
      description: 'Returns application metrics in Prometheus text format.

        Used by monitoring systems (Prometheus, Grafana, etc.) for telemetry collection.


        **Format:** Prometheus exposition format (text/plain)

        **Endpoint type:** Scrape endpoint (intended for machine consumption)

        **Metrics included:**

        - HTTP request duration and status codes

        - Database connection pool stats

        - Business logic metrics (repos registered, teams created, etc.)

        - Custom application metrics


        **Authentication:** Not required (typically scraped by internal monitoring)

        **Rate limit:** Standard rate limiting (or exempt in some deployments)'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: Prometheus metrics in text format
          content:
            text/plain:
              schema:
                type: string
                example: '# HELP http_requests_total Total HTTP requests\n# TYPE http_requests_total counter\nhttp_requests_total{method="GET",status="200"} 1234\n'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /ready/temporal/smoke:
    get:
      operationId: temporalSmokeTest
      summary: Temporal workflow engine smoke test
      description: 'Quick connectivity and health check for Temporal workflow engine.

        Returns status of Temporal connection and basic functionality.


        **Purpose:** Verification endpoint for deployment health checks

        **Timeout:** ~5 seconds (fail-fast)


        **Authentication:** Not required (health check endpoint)'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: Temporal service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    - degraded
                    example: ok
                  message:
                    type: string
                    example: Temporal server is reachable
        '503':
          description: Temporal service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - error
                    example: error
                  message:
                    type: string
                    example: Unable to reach Temporal server
  /ready/gitlab/smoke:
    get:
      operationId: gitlabSmokeTest
      summary: GitLab integration smoke test
      description: 'Quick connectivity and health check for GitLab integration.

        Returns status of GitLab API endpoint and authentication.


        **Purpose:** Verification endpoint for deployment health checks

        **Timeout:** ~5 seconds (fail-fast)


        **Authentication:** Not required (health check endpoint)'
      tags:
      - Miscellaneous
      security: []
      responses:
        '200':
          description: GitLab service is healthy
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - ok
                    - degraded
                    example: ok
                  message:
                    type: string
                    example: GitLab server is reachable
        '503':
          description: GitLab service unavailable
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - error
                    example: error
                  message:
                    type: string
                    example: Unable to reach GitLab server
components:
  schemas:
    ErrorResponse:
      type: object
      description: Standard error response returned by all endpoints on failure.
      required:
      - success
      - error
      properties:
        success:
          type: boolean
          description: Always `false` for error responses.
          enum:
          - false
        error:
          type: string
          description: Human-readable error message describing what went wrong. Do not parse this programmatically — use HTTP status codes for control flow.
          example: Invalid request parameters
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'JWT token obtained from the auth service (/api/auth/token).

        Token is validated using JWKS from the auth service.

        Required claims: sub (user_id), email, name, tier.

        '