Sageox Repository API
Repository initialization and merge operations. `initRepo` creates or reconnects a repository with SageOx (idempotent). `mergeRepos` combines ledger data when repositories are merged.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/sageox-repository-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: SageOx Repository 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: Repository
description: Repository initialization and merge operations. `initRepo` creates or reconnects a repository with SageOx (idempotent). `mergeRepos` combines ledger data when repositories are merged.
paths:
/api/v1/repo/init:
post:
operationId: initRepo
summary: Initialize repository tracking
description: 'Registers a git repository with SageOx and creates an associated team.
**Authentication:** Optional
- **Authenticated:** User becomes owner of newly created team
- **Unauthenticated:** Creates orphan team (can be claimed later)
Idempotent: if repo_id already exists, returns existing repo/team info.
Users can request to merge teams via /api/v1/repo/merge.'
tags:
- Repository
security:
- BearerAuth: []
- {}
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- repo_id
- type
- init_at
properties:
repo_id:
type: string
description: Client-generated repo identifier (repo_<uuidv7>)
pattern: ^repo_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
example: repo_01934f5a-8b9c-7def-b012-3456789abcde
type:
type: string
description: VCS type (git supported, svn planned)
enum:
- git
example: git
init_at:
type: string
format: date-time
description: Timestamp from .repo_<id> marker file
example: '2025-12-18T16:30:00Z'
repo_salt:
type: string
description: Initial commit hash for salted remote hashing (optional, omitted in --offline mode)
example: abc123def456789...
repo_remote_hashes:
type: array
description: SHA256(repo_salt + remote_url) for each git remote (optional, omitted in --offline mode)
items:
type: string
example:
- sha256:a1b2c3d4...
- sha256:e5f6g7h8...
is_public:
type: boolean
description: When true, prevents automatic merging with repos that have matching hashes (fork protection)
example: false
created_by_email:
type: string
format: email
description: Git user.email from local config (optional, omitted in --offline mode)
example: jane@example.com
created_by_name:
type: string
description: Git user.name from local config (optional, omitted in --offline mode)
example: Jane Dev
examples:
full:
summary: Full request with all optional fields
value:
repo_id: repo_01934f5a-8b9c-7def-b012-3456789abcde
type: git
init_at: '2025-12-18T16:30:00Z'
repo_salt: abc123def456789...
repo_remote_hashes:
- sha256:a1b2c3d4...
is_public: false
created_by_email: jane@example.com
created_by_name: Jane Dev
offline:
summary: Minimal request (--offline mode)
value:
repo_id: repo_01934f5a-8b9c-7def-b012-3456789abcde
type: git
init_at: '2025-12-18T16:30:00Z'
responses:
'200':
description: Repository already exists (idempotent response)
content:
application/json:
schema:
type: object
required:
- repo_id
properties:
repo_id:
type: string
description: The existing repo_id
example: repo_01934f5a-8b9c-7def-b012-3456789abcde
team_id:
type: string
description: ID of the existing team
example: team_abc123xyz
web_base_url:
type: string
format: uri
description: Base URL for web UI (enterprise deployments)
example: https://sageox.ai
'201':
description: Repository registered successfully
content:
application/json:
schema:
type: object
required:
- repo_id
- team_id
properties:
repo_id:
type: string
description: The registered repo_id
example: repo_01934f5a-8b9c-7def-b012-3456789abcde
team_id:
type: string
description: ID of the newly created team
example: team_abc123xyz
web_base_url:
type: string
format: uri
description: Base URL for web UI (enterprise deployments)
example: https://sageox.ai
claim_code:
type: string
description: Code for claiming team ownership (unauthenticated requests only)
example: abc123xyz
claim_url:
type: string
format: uri
description: Full URL for browser-based team claiming (unauthenticated requests only)
example: https://sageox.ai/team/claim?code=abc123xyz&team=team_abc123xyz
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
missing_repo_id:
value:
error: repo_id is required
invalid_repo_id:
value:
error: repo_id must be in format repo_<uuidv7>
invalid_type:
value:
error: type must be 'git'
'500':
description: Internal server error
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
/api/v1/repo/merge:
post:
operationId: mergeRepos
summary: Merge concurrent repository registrations
description: 'Called by ox-cli when it detects multiple .repo_* files (concurrent inits).
Determines the canonical repo_id based on UUIDv7 timestamps (time-sortable).
**Current implementation:** Logs the merge request and returns the canonical repo_id.
Full merge logic is planned for a future release.'
tags:
- Repository
security:
- BearerAuth: []
- {}
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- repo_ids
properties:
repo_ids:
type: array
description: Array of repo_<uuidv7> identifiers to merge
minItems: 2
items:
type: string
pattern: ^repo_[0-9a-f]{8}-[0-9a-f]{4}-7[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$
example:
- repo_01934f5a-8b9c-7def-b012-3456789abcde
- repo_01934f5b-1234-7abc-9012-def456789012
responses:
'200':
description: Merge processed successfully
content:
application/json:
schema:
type: object
required:
- canonical_repo_id
- merged
properties:
canonical_repo_id:
type: string
description: The earliest repo_id by UUIDv7 timestamp (becomes canonical)
example: repo_01934f5a-8b9c-7def-b012-3456789abcde
merged:
type: boolean
description: Whether merge was processed (always true for now)
example: true
'400':
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
insufficient_ids:
value:
error: at least 2 repo_ids required for merge
invalid_format:
value:
error: all repo_ids must be in format repo_<uuidv7>
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.
'