SageOx Miscellaneous API
The Miscellaneous API from SageOx — 12 operation(s) for miscellaneous.
OpenAPI Specification
openapi: 3.1.0
info:
title: SageOx Admin Miscellaneous API
version: 1.0.0
description: "# API Reference\n\n## Overview\n\nSageOx 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). The SageOx API provides programmatic access to manage repositories, recordings, notifications, and team data with high performance and reliability.\n\n## Base URLs\n\n| Environment | URL |\n|---|---|\n| Local Development | `http://localhost:3000` |\n| Test | `https://test.sageox.ai` |\n| Production | `https://sageox.ai` |\n\n## Authentication\n\nAll requests to the SageOx API require authentication via JWT tokens issued by the Better Auth service.\n\nInclude your token in the `Authorization` header:\n```\nAuthorization: Bearer <token>\n```\n\n**Initial Auth Flow (CLI)**\n- CLI initiates device flow to obtain initial credentials\n- Exchange device code for JWT token\n- Store token securely for subsequent API requests\n- Refresh token when expired\n\n**Authenticated Endpoints**\n- Pass JWT in `Authorization: Bearer <token>` header\n- Tokens contain user identity and team membership\n- Invalid or expired tokens return 401 Unauthorized\n\n## Response Format\n\n### Success\nStandard response format with optional pagination metadata:\n```json\n{\n \"success\": true,\n \"data\": { ... }\n}\n```\n\n### Error\nAll errors follow a consistent format:\n```json\n{\n \"success\": false,\n \"error\": \"Human-readable error description\"\n}\n```\n\n**Status Codes**\n- `400` — Bad Request: Invalid parameters or malformed request\n- `401` — Unauthorized: Missing or invalid authentication token\n- `403` — Forbidden: Insufficient permissions for this resource\n- `404` — Not Found: Resource does not exist\n- `409` — Conflict: Request conflicts with current state (e.g., duplicate)\n- `429` — Rate Limited: Too many requests; retry with backoff\n- `500` — Internal Error: Server error; contact support if persistent\n\n## Pagination\n\nList endpoints support cursor-based pagination via query parameters:\n\n**Query Parameters**\n- `limit` — Number of results per page (default: 20, max: 100)\n- `offset` — Number of results to skip (default: 0)\n\n**Response Metadata**\nList responses include pagination info:\n```json\n{\n \"success\": true,\n \"data\": [ ... ],\n \"meta\": {\n \"total\": 150,\n \"limit\": 20,\n \"offset\": 0,\n \"hasMore\": true\n }\n}\n```\n\n## ID Formats\n\nResources use standardized ID formats for easy identification:\n\n| Resource | Format | Length | Example |\n|---|---|---|---|\n| Team | `team_<cuid2>` | 10 chars | `team_abc1234567` |\n| User | `usr_<cuid2>` | 10 chars | `usr_xyz9876543` |\n| Repository | `repo_<uuidv7>` | 36 chars | `repo_01934f5a-8b9c-7def-abcd-0123456789ab` |\n| Recording | `rec_<uuidv7>` | 36 chars | `rec_01934f5a-8b9c-7def-abcd-0123456789ab` |\n| Image | `img_<uuidv7>` | 36 chars | `img_01934f5a-8b9c-7def-abcd-0123456789ab` |\n| Notification | `notif_<cuid2>` | 14 chars | `notif_ab1cd2ef3g` |\n\nUse these IDs for all API operations. IDs are unique across environments.\n\n## Rate Limiting\n\nThe API applies rate limiting to protect against abuse and ensure fair access:\n\n**Authenticated Endpoints**\n- Limited per user: depends on subscription tier\n- Quota resets hourly\n\n**Unauthenticated Endpoints**\n- Limited per IP address\n- More restrictive than authenticated limits\n\nWhen rate limited, the API returns `429 Too Many Requests`. Retry requests with exponential backoff:\n```\nwait = min(2^attempt * 100ms, 10s)\n```\n\n## Timestamps\n\nAll timestamps in API responses use RFC 3339 / ISO 8601 format in UTC:\n```\n2025-12-03T10:30:00Z\n```\n\nUse this format when providing timestamps in requests as well. The API rejects timestamps in other formats.\n\n## SDKs & Tools\n\n- **OpenAPI Spec** — Full schema available at `/api/openapi.json`\n- **Postman Collection** — Import from `/api/postman.json` for interactive exploration\n- **CLI** — Use `ox` CLI for command-line access\n"
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.
'