openapi: 3.0.3
info:
title: IronBridge API
description: |
REST API for IronBridge (Chat Session Manager) - a unified platform for harvesting,
managing, and analyzing AI chat sessions across multiple providers and tools.
## Authentication
Currently the API supports local access without authentication. Enterprise features
include SSO/SAML authentication and API key-based access.
## Rate Limiting
Rate limiting is optional and configurable per-installation.
## WebSocket
Real-time updates are available via WebSocket at `ws://<host>/ws`. Note that
`/ws` is mounted at the server root, not under the `/api` base URL below.
Client frames are tagged JSON: `subscribe`, `unsubscribe`, `ping`,
`sync_request`, `stream_start`, `stream_cancel`, `stream_input` and
`agent_command`. Every one of them is answered.
`sync_request` returns the same delta as `GET /sync/delta?from=N`, as one
`sync_event` per change in version order. Two cases answer with an error
instead of an empty result, because sending nothing would read as "you are
up to date": `history_truncated` when the requested version has aged out of
the retained event history, and `version_ahead` when the client's version
exceeds the server's. Both mean the client needs a full snapshot.
The stream operations and `agent_command` are **not implemented** on this
server and answer `stream_error` / `error` with code `unsupported`. They are
part of the protocol and are refused explicitly rather than ignored, so a
caller is never left waiting on a reply that is not coming.
## Scope
This document describes only endpoints the server actually routes. Paths that
were documented but never implemented were removed in 2.0.0; see `ROADMAP.md`
for the ones still intended.
version: 2.0.0
contact:
name: Nervosys LLC
url: https://github.com/nervosys/IronBridge
license:
name: AGPL-3.0-only
url: https://www.gnu.org/licenses/agpl-3.0.html
servers:
- url: http://localhost:8787/api
description: Local development server
- url: https://api.ironbridge.io/api
description: Production server (when deployed)
tags:
- name: Health
description: System health checks
- name: System
description: System management operations
- name: Workspaces
description: Workspace management
- name: Sessions
description: Chat session management
- name: Providers
description: AI provider configuration
- name: Agents
description: AI agent management
- name: Swarms
description: Agent swarm orchestration
- name: Chat
description: Chat completions
- name: Search
description: Search operations
- name: Statistics
description: Usage statistics
- name: Inbox
description: Agent notifications, messages, permission requests and workflow runs
- name: Settings
description: Application settings
- name: Sharing
description: Local, revocable share links -- readable through this server only
- name: MCP
description: Model Context Protocol tool discovery and invocation
- name: SWE
description: Software-engineering project context -- projects, memory and rules
- name: Auth
description: Accounts, sessions and subscription state (mounted at the server root)
- name: Sync
description: Change feed and state snapshots (mounted at the server root)
- name: Recording
description: Live session recording and recovery (mounted at the server root)
- name: Webhooks
description: Outbound webhook registration and delivery history (mounted at the server root)
- name: Audit
description: Audit event log (enterprise build only)
- name: Retention
description: Data retention policies (enterprise build only)
- name: SSO
description: SAML single sign-on (enterprise build only)
- name: OIDC
description: OpenID Connect single sign-on (enterprise build only)
- name: Documents
description: The knowledge base -- documents, their chunks and semantic search
- name: Datasets
description: Locally uploaded datasets
- name: Catalog
description: A read-only proxy to the Hugging Face Hub
- name: Downloads
description: Model and dataset downloads to local disk
- name: Training
description: Fine-tuning jobs, submitted to a provider
- name: Research
description: arXiv search, and the papers the user saved
- name: Notes
description: Clippings saved from a page by the browser extension
paths:
/health:
get:
tags: [Health]
summary: Health check
description: Check if the API server is running and healthy
operationId: healthCheck
responses:
"200":
description: Server is healthy
content:
application/json:
schema:
$ref: "#/components/schemas/HealthResponse"
/system/info:
get:
tags: [System]
summary: Get system information
operationId: getSystemInfo
responses:
"200":
description: System information
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SystemInfo"
/workspaces:
get:
tags: [Workspaces]
summary: List workspaces
operationId: listWorkspaces
parameters:
- $ref: "#/components/parameters/limitParam"
- $ref: "#/components/parameters/offsetParam"
responses:
"200":
description: List of workspaces
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/WorkspaceList"
/workspaces/{id}:
get:
tags: [Workspaces]
summary: Get workspace by ID
operationId: getWorkspace
parameters:
- $ref: "#/components/parameters/workspaceId"
responses:
"200":
description: Workspace details
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Workspace"
"404":
$ref: "#/components/responses/NotFound"
/sessions:
get:
tags: [Sessions]
summary: List sessions
operationId: listSessions
parameters:
- $ref: "#/components/parameters/limitParam"
- $ref: "#/components/parameters/offsetParam"
- name: workspace_id
in: query
schema:
type: string
format: uuid
- name: provider
in: query
schema:
type: string
- name: archived
in: query
schema:
type: boolean
responses:
"200":
description: List of sessions
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SessionList"
post:
tags: [Sessions]
summary: Create a session
operationId: createSession
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateSession"
responses:
"201":
description: Session created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Session"
/sessions/{id}:
get:
tags: [Sessions]
summary: Get session by ID
operationId: getSession
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Session details
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SessionDetail"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Sessions]
summary: Delete a session
description: Also removes the session's rows from the normalized message table.
operationId: deleteSession
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Session deleted
"404":
$ref: "#/components/responses/NotFound"
/sessions/{id}/messages:
post:
tags: [Sessions]
summary: Append a message to a session
description: >
An assistant message attaches to the trailing prompt rather than
starting a new exchange, matching how sessions are read back.
operationId: createMessage
parameters:
- $ref: "#/components/parameters/sessionId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateMessage"
responses:
"201":
description: Message appended
"400":
description: Empty content or unsupported role
"404":
$ref: "#/components/responses/NotFound"
/sessions/{id}/checkpoints:
get:
tags: [Sessions]
summary: List checkpoints for a session
operationId: listCheckpoints
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Checkpoints, newest first
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Checkpoint"
post:
tags: [Sessions]
summary: Create a checkpoint
operationId: createCheckpoint
parameters:
- $ref: "#/components/parameters/sessionId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateCheckpoint"
responses:
"201":
description: Checkpoint created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Checkpoint"
"404":
$ref: "#/components/responses/NotFound"
/sessions/{id}/commits:
get:
tags: [Sessions]
summary: Git commits for the session's workspace
description: >
Empty when the workspace is not a git repository or git is unavailable;
that is the honest answer, not an error.
operationId: listSessionCommits
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Commits, newest first
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/GitCommit"
"404":
$ref: "#/components/responses/NotFound"
/providers:
get:
tags: [Providers]
summary: List providers
operationId: listProviders
responses:
"200":
description: List of configured providers
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Provider"
/providers/{id}:
put:
tags: [Providers]
summary: Switch a provider on or off
description: >
Persists the one mutable field on a provider. The catalogue itself is
compiled in, so nothing else about a provider can be changed here. An
id outside the catalogue is a 404 rather than a stored setting for a
provider that does not exist.
operationId: updateProvider
parameters:
- name: id
in: path
required: true
description: Catalogue id, as returned by listProviders.
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [enabled]
properties:
enabled:
type: boolean
responses:
"200":
description: The provider, with the new setting applied
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Provider"
"404":
$ref: "#/components/responses/NotFound"
/agents:
get:
tags: [Agents]
summary: List agents
operationId: listAgents
responses:
"200":
description: List of agents
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Agent"
post:
tags: [Agents]
summary: Create agent
operationId: createAgent
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateAgent"
responses:
"201":
description: Agent created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Agent"
/agents/{id}:
get:
tags: [Agents]
summary: Get agent by ID
operationId: getAgent
parameters:
- $ref: "#/components/parameters/agentId"
responses:
"200":
description: Agent details
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Agent"
put:
tags: [Agents]
summary: Update agent
operationId: updateAgent
parameters:
- $ref: "#/components/parameters/agentId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateAgent"
responses:
"200":
description: Agent updated
delete:
tags: [Agents]
summary: Delete agent
operationId: deleteAgent
parameters:
- $ref: "#/components/parameters/agentId"
responses:
"204":
description: Agent deleted
/stats/overview:
get:
tags: [Statistics]
summary: Get statistics overview
operationId: getStatsOverview
responses:
"200":
description: Statistics overview
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/StatsOverview"
/stats/providers:
get:
tags: [Statistics]
summary: Per-provider session and message counts
description: >
Token counts are reported as 0 where the store holds none, rather than
being estimated.
operationId: getProviderStats
responses:
"200":
description: Counts keyed by provider
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
additionalProperties:
$ref: "#/components/schemas/ProviderStats"
/search:
get:
tags: [Search]
summary: Search sessions and messages
description: >
Substring matching over session titles and, where the normalized
message table exists, message content. Not semantic search -- there is
no embedding index behind this route.
operationId: search
parameters:
- name: q
in: query
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 500
responses:
"200":
description: Matches
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/SearchResult"
/swarms:
get:
tags: [Swarms]
summary: List swarms
operationId: listSwarms
responses:
"200":
description: Swarms
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
type: object
post:
tags: [Swarms]
summary: Create a swarm
operationId: createSwarm
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, orchestration, agents]
properties:
name:
type: string
description:
type: string
orchestration:
type: string
enum: [sequential, parallel, hierarchical, debate]
agents:
type: array
items:
type: object
max_iterations:
type: integer
responses:
"200":
description: Swarm created
/swarms/{id}/agents:
post:
tags: [Swarms]
summary: Add an agent to a swarm
description: >
Membership is stored on the swarm as `{agent_id, role}` records, so
this reads the list, edits it and writes it back.
Adding an agent that is already a member updates its role rather than
duplicating it — a swarm cannot hold one agent in two roles, and
refusing would make the obvious way to change a role an error.
The agent must exist. A membership pointing at no agent is a dangling
reference that later reads as data. Note the asymmetry: `POST /swarms`
does not currently check the ids in its `agents` list.
operationId: addSwarmAgent
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [agent_id, role]
properties:
agent_id:
type: string
description: >
snake_case, as the server spells it — this body
deserializes into a Rust struct with no serde rename.
role:
type: string
example: coordinator
responses:
"200":
description: The swarm's membership after the change
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
id:
type: string
agents:
type: array
items:
$ref: "#/components/schemas/SwarmAgent"
updatedAt:
type: integer
format: int64
"400":
description: agent_id or role is blank
"404":
description: No such swarm, or no such agent
/swarms/{id}/agents/{agent_id}:
delete:
tags: [Swarms]
summary: Remove an agent from a swarm
description: >
A 404 when that agent was not a member — reporting a removal that
removed nothing is exactly the failure this API tries not to have.
operationId: removeSwarmAgent
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: agent_id
in: path
required: true
schema:
type: string
responses:
"200":
description: The swarm's membership after the removal
"404":
description: No such swarm, or that agent was not a member
/swarms/{id}:
get:
tags: [Swarms]
summary: Get a swarm
operationId: getSwarm
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Swarm
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Swarms]
summary: Delete a swarm
operationId: deleteSwarm
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Deleted
"404":
$ref: "#/components/responses/NotFound"
put:
tags: [Swarms]
summary: Update a swarm
description: Omitted fields keep their stored value.
operationId: updateSwarm
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateSwarm"
responses:
"200":
description: Swarm updated
"404":
$ref: "#/components/responses/NotFound"
/providers/{id}/test:
post:
tags: [Providers]
summary: Test provider connectivity
description: >
Only locally hosted providers (ollama, lmstudio) expose an endpoint this
server can reach; anything else returns 501 rather than a success that
tested nothing.
operationId: testProvider
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Provider reachable
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
success:
type: boolean
latency:
type: integer
description: Round-trip time in milliseconds
"501":
description: No connectivity test exists for this provider
"502":
description: Provider unreachable
/chat/completions:
post:
tags: [Chat]
summary: Proxy a completion to the configured model
description: >
Forwards to an OpenAI-compatible endpoint configured with
OPENAI_API_KEY and OPENAI_BASE_URL. Returns 503 when no model is
configured; it never substitutes a canned reply.
operationId: chatCompletion
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ChatCompletionRequest"
responses:
"200":
description: Completion
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/ChatCompletionResponse"
"400":
description: No messages supplied
"502":
description: Model unreachable or returned an error
"503":
description: No model configured on the server
/harvest:
post:
tags: [System]
summary: Run an incremental harvest
description: >
Walks the filesystem for new sessions. Can take minutes; runs on a
blocking thread.
operationId: runHarvest
responses:
"200":
description: Harvest finished
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/HarvestResult"
/research/papers:
get:
tags: [Research]
summary: Search arXiv
description: >
A read-only proxy to arXiv's public API. The host is compiled in and
only the query is caller-controlled, so it cannot be pointed at an
arbitrary URL. A descriptive User-Agent is sent and the page size is
capped, as arXiv asks.
`totalResults` is arXiv's own count for the query, so a page of 20 out
of 176,736 is distinguishable from 20 and no more.
An unreachable arXiv is a 502, never an empty list.
operationId: searchPapers
x-ironbridge-probe: needs-network
parameters:
- name: q
in: query
required: true
schema:
type: string
example: retrieval augmented generation
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 50
- name: start
in: query
description: Offset into the result set, for paging.
schema:
type: integer
default: 0
responses:
"200":
description: Matching papers
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/PaperResults"
"400":
description: q is missing or empty
"502":
description: arXiv was unreachable or returned something unusable
/research/saved:
get:
tags: [Research]
summary: List saved papers
description: Most recently saved first. Held by this server, not by arXiv.
operationId: listSavedPapers
responses:
"200":
description: Saved papers
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Paper"
post:
tags: [Research]
summary: Save a paper
description: >
Idempotent — saving the same paper twice is what an unsure client does
and is not an error.
operationId: savePaper
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [paper]
properties:
paper:
$ref: "#/components/schemas/Paper"
responses:
"200":
description: Saved
"400":
description: paper.arxivId is missing
/research/saved/{id}:
delete:
tags: [Research]
summary: Unsave a paper
operationId: unsavePaper
parameters:
- name: id
in: path
required: true
description: The arXiv id.
schema:
type: string
responses:
"200":
description: Removed
"404":
$ref: "#/components/responses/NotFound"
/notes:
get:
tags: [Notes]
summary: List clippings
description: >
Most recently saved first, ordered by `createdAt` — this server's
clock, not the client's.
`q` is a substring match over the content, source and url. Note that
`%` and `_` in `q` are SQL LIKE wildcards; a search for `%` matches
everything.
operationId: listNotes
parameters:
- name: limit
in: query
schema:
type: integer
default: 100
maximum: 500
- name: q
in: query
description: Substring match over content, source and url.
schema:
type: string
responses:
"200":
description: Saved clippings
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Note"
post:
tags: [Notes]
summary: Save a clipping
description: >
The body the browser extension's "Save Selection to IronBridge" context
menu already sends. It also sends `"type": "note"`, a constant, which
is ignored — a column whose every value is the same word records
nothing.
Not idempotent: the same sentence selected twice is two clippings, and
there is no key on which the second could be recognised as the first.
operationId: createNote
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [content]
properties:
content:
type: string
description: The selected text, as it was selected.
source:
type: string
example: arxiv.org
url:
type: string
timestamp:
type: string
description: >
The client's own clock. Stored verbatim as `capturedAt`
and never parsed; ordering uses the server's `createdAt`.
responses:
"201":
description: Saved
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Note"
"400":
description: content is empty or longer than 100,000 characters
/notes/{id}:
get:
tags: [Notes]
summary: Get one clipping
operationId: getNote
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The clipping
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Note"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Notes]
summary: Delete a clipping
operationId: deleteNote
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Removed
"404":
$ref: "#/components/responses/NotFound"
/settings:
get:
tags: [Settings]
summary: Get settings
operationId: getSettings
responses:
"200":
description: Application settings
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Settings"
put:
tags: [Settings]
summary: Update settings
operationId: updateSettings
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/Settings"
responses:
"200":
description: Settings updated
/stats:
get:
tags: [Statistics]
summary: Database statistics
description: Identical payload to `/stats/overview`; both are served by the same handler.
operationId: getStats
responses:
"200":
description: Statistics
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/StatsOverview"
/sessions/search:
get:
tags: [Search]
summary: Search session titles
description: >
Substring match over session titles. This is the endpoint the web
client's search box uses; `/search` additionally covers message
content.
operationId: searchSessions
parameters:
- name: q
in: query
required: true
schema:
type: string
- $ref: "#/components/parameters/limitParam"
responses:
"200":
description: Matching sessions
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
query:
type: string
results:
type: array
items:
$ref: "#/components/schemas/Session"
/system/health:
get:
tags: [System]
summary: Server and database health
operationId: getSystemHealth
responses:
"200":
description: Health report
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SystemHealth"
/system/providers/health:
get:
tags: [Providers]
summary: Provider connectivity
description: >
Locally hosted providers are probed at their declared endpoint.
Cloud providers report `unknown`: the server holds no credentials for
them, so any other verdict would be a guess.
operationId: getProviderHealth
responses:
"200":
description: One row per provider
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/ProviderHealth"
/settings/accounts:
get:
tags: [Settings]
summary: List provider accounts
description: >
Stored provider accounts, newest first. The credential itself is never
returned -- only the metadata around it. Credentials are held encrypted;
see createAccount.
operationId: listAccounts
responses:
"200":
description: Accounts
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/ProviderAccount"
post:
tags: [Settings]
summary: Add a provider account
description: >
Stores a credential for a provider, encrypted with AES-256-GCM under a
key derived from the server's `IRONBRIDGE_MASTER_KEY` environment variable
and a per-install salt.
If `IRONBRIDGE_MASTER_KEY` is unset the request is refused with a 400 rather
than the credential being written in the clear. Set it in the server's
environment and restart.
The credential is never returned by any endpoint, including this one:
the response carries only the account metadata.
operationId: createAccount
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [provider, credentials]
properties:
provider:
type: string
description: Provider name; also used to derive the account's display name.
example: Anthropic
credentials:
type: object
description: Opaque credential blob, encrypted before storage and never read back out.
additionalProperties: true
responses:
"200":
description: Account created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/ProviderAccount"
"400":
description: >
No encryption key is configured, so the credential was not stored.
content:
application/json:
schema:
$ref: "#/components/schemas/ApiEnvelope"
/settings/accounts/{id}:
delete:
tags: [Settings]
summary: Remove a provider account
operationId: deleteAccount
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Account removed
/catalog/models:
get:
tags: [Catalog]
summary: Search models on the Hugging Face Hub
description: >
A read-only proxy to the Hub's public search. The host is compiled in;
only the query is caller-controlled, so this cannot be pointed at an
arbitrary URL.
It searches and does not download: nothing here writes a file. Fetching
an artifact needs a destination, a free-space guard and a background
job with progress, none of which exist.
No credential is required. Setting `HUGGINGFACE_TOKEN` on the server
only raises the Hub's anonymous rate limit.
An unreachable Hub is a 502, never an empty list -- "the Hub is down"
and "nothing matched" are different answers and an empty table cannot
tell them apart.
operationId: searchCatalogModels
x-ironbridge-probe: needs-network
parameters:
- name: q
in: query
description: Free-text search. Omitted or blank lists what the Hub returns by default.
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
"200":
description: Matching models
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/CatalogResults"
"502":
description: The Hub was unreachable, rate-limited, or returned something unusable
/catalog/files:
get:
tags: [Catalog]
summary: List a Hub repository's files, with sizes
description: >
Sizes are what makes a download decidable: without them a client
cannot warn about a 5 GB file and the server cannot check the disk
before starting. The Hub reports the real size for LFS files here, not
the pointer size.
Directories are omitted — there is nothing to download about one.
operationId: listRepoFiles
x-ironbridge-probe: needs-network
parameters:
- name: kind
in: query
required: true
schema:
type: string
enum: [models, datasets]
- name: id
in: query
required: true
description: >
`author/name`, or a bare name for the canonical repositories. The
shape is validated before it reaches a URL path.
schema:
type: string
example: openai-community/gpt2
responses:
"200":
description: The repository's files
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
kind:
type: string
id:
type: string
files:
type: array
items:
$ref: "#/components/schemas/RepoFile"
"400":
description: kind or id missing, or an id that is not a repository id
"502":
description: The Hub was unreachable, or has no such repository
/catalog/datasets:
get:
tags: [Catalog]
summary: Search datasets on the Hugging Face Hub
description: >
As `searchCatalogModels`, for datasets.
Note this is the *catalogue* -- artifacts published elsewhere. The
local store of datasets uploaded to this server is `/datasets`, and the
two are deliberately separate: the data flows in opposite directions.
operationId: searchCatalogDatasets
x-ironbridge-probe: needs-network
parameters:
- name: q
in: query
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 20
maximum: 100
responses:
"200":
description: Matching datasets
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/CatalogResults"
"502":
description: The Hub was unreachable, rate-limited, or returned something unusable
/datasets:
get:
tags: [Datasets]
summary: List stored datasets
description: >
Newest first, without their entries: a listing carrying every record
would be the whole store in one response.
Note there are two things the clients have called a "dataset". This is
the local store -- collections the user uploads and this server holds.
A remote catalogue to download from would be a separate feature; the
data flows the other way and the two are not merged here.
operationId: listDatasets
responses:
"200":
description: Datasets
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/Dataset"
post:
tags: [Datasets]
summary: Upload a dataset
description: >
Stores the records verbatim as JSON, in one transaction: a dataset
whose entries were half written would list with a count it does not
have.
`entryCount` and `sizeBytes` are computed from what was stored and are
ignored if sent. A client-supplied size is a number nobody checked.
operationId: createDataset
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, entries]
properties:
name:
type: string
type:
type: string
description: >
A closed set, because the clients switch on it for their
icons and filters; an unrecognised value is a 400 rather
than something that renders as nothing.
enum: [conversations, documents, qa, custom]
default: custom
format:
type: string
description: Free-form label for the record shape. Defaults to `json`.
entries:
type: array
description: >
The records. At most 50,000 per request -- the body is
parsed into memory and written in one transaction, and
there is no streaming import yet.
items: {}
responses:
"200":
description: Dataset stored
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Dataset"
"400":
description: Name or entries missing, too many entries, or an unknown type
/datasets/{id}:
get:
tags: [Datasets]
summary: Get one dataset's metadata
description: Its records come from `/datasets/{id}/entries`.
operationId: getDataset
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The dataset
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Dataset"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Datasets]
summary: Delete a dataset and its entries
operationId: deleteDataset
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Dataset removed
"404":
$ref: "#/components/responses/NotFound"
/datasets/{id}/entries:
get:
tags: [Datasets]
summary: Read a page of a dataset's records
description: >
In upload order. Paged because a dataset may hold 50,000 records and
nothing renders that many at once.
An unknown dataset is a 404 rather than an empty page: a missing
dataset and a page past the end would otherwise be the same answer.
operationId: listDatasetEntries
parameters:
- name: id
in: path
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 50
maximum: 500
- name: offset
in: query
schema:
type: integer
default: 0
responses:
"200":
description: A page of records
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DatasetEntryPage"
"404":
$ref: "#/components/responses/NotFound"
/training/validate:
get:
tags: [Training]
summary: Check a dataset against a provider's fine-tuning rules
description: >
Local, free and offline — no provider is contacted. That is the point:
a bad dataset otherwise fails at the provider *after* the upload, which
has already been paid for.
Reports every problem it finds rather than the first, so a caller can
fix them in one pass. Capped at 20, because a systematically broken
dataset has one problem per row.
operationId: validateTrainingDataset
x-ironbridge-probe: needs-prior-state
parameters:
- name: datasetId
in: query
required: true
schema:
type: string
responses:
"200":
description: The verdict, with any problems
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DatasetValidation"
"400":
description: datasetId missing
"404":
$ref: "#/components/responses/NotFound"
/training/jobs:
get:
tags: [Training]
summary: List fine-tuning jobs
description: >
Newest first. Every unfinished job is refreshed from the provider on
this request, so the status shown is the provider's current one.
With no provider configured, or when a refresh fails, the stored
status is returned with `refreshError` set rather than the whole list
failing. That field is how a stale status is told apart from a current
one.
operationId: listTrainingJobs
responses:
"200":
description: Jobs
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/TrainingJob"
post:
tags: [Training]
summary: Submit a dataset for fine-tuning
description: >
IronBridge does not train anything. It converts the dataset to JSONL,
uploads it to the provider configured with `OPENAI_API_KEY`, creates a
fine-tuning job there, and records the provider's job id.
The dataset is validated locally first and the request is refused
without uploading if it would not pass — the upload is the part that
costs.
Note there is no progress figure anywhere in the response. A
fine-tuning API reports a status, and once finished a trained-token
count and the resulting model name. It reports no percentage, no ETA
and no GPU, so none are invented here.
operationId: startTraining
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [datasetId, baseModel]
properties:
datasetId:
type: string
description: A dataset from `/datasets`.
baseModel:
type: string
description: The provider's identifier for the model to fine-tune.
example: gpt-4o-mini-2024-07-18
suffix:
type: string
description: Optional label the provider appends to the resulting model's name.
responses:
"200":
description: The job, as the provider created it
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/TrainingJob"
"400":
description: >
datasetId or baseModel missing, or a dataset that would not pass
the provider's rules. The response carries a `problems` array.
"404":
description: No dataset with that id
"502":
description: The provider refused the upload or the job
"503":
description: No provider configured
/training/jobs/{id}:
get:
tags: [Training]
summary: Read one fine-tuning job
description: Refreshed from the provider unless it has already finished.
operationId: getTrainingJob
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The job
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/TrainingJob"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Training]
summary: Cancel a running job, or forget a finished one
description: >
A running job is cancelled at the provider and the refreshed job is
returned. A finished job's record is deleted, which needs no provider.
operationId: cancelTrainingJob
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Cancelled, or the record was removed
"404":
$ref: "#/components/responses/NotFound"
"502":
description: The provider refused the cancellation
"503":
description: No provider configured, and the job has not finished
/downloads:
get:
tags: [Downloads]
summary: List download jobs
description: >
Newest first.
A job left `running` by a server that stopped is reported as failed
rather than left running: nothing will ever advance it, and a progress
bar that never moves is indistinguishable from a slow download.
operationId: listDownloads
responses:
"200":
description: Download jobs
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/DownloadJob"
post:
tags: [Downloads]
summary: Start downloading one file from a Hub repository
description: >
Returns immediately with a job to poll. The files are large enough that
a handler which downloaded before answering would time out every client
in front of it and report no progress on the way.
Files land under `IRONBRIDGE_DOWNLOAD_DIR`, or a `downloads` directory
beside the database, as `<kind>/<repo id>/<path>`.
Refused before a job exists when: the repository does not publish that
path; the path could escape the download directory; the file exceeds
`IRONBRIDGE_MAX_DOWNLOAD_BYTES`; the destination already exists; or the file
would not fit on the volume with 2 GB left spare. Filling the volume
would take the database with it.
The URL is built server-side from the validated repository and path
against a compiled-in host — it is never supplied by the caller.
operationId: startDownload
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [kind, repoId, filePath]
properties:
kind:
type: string
enum: [models, datasets]
repoId:
type: string
example: openai-community/gpt2
filePath:
type: string
description: As `listRepoFiles` reports it. Must exist in that repository.
example: config.json
responses:
"200":
description: The job, already running
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DownloadJob"
"400":
description: >
Unknown kind, unusable repository id or path, a file the repository
does not have, a destination that already exists, a file over the
size cap, or not enough free space
"502":
description: The Hub was unreachable while checking the file
/downloads/{id}:
get:
tags: [Downloads]
summary: Poll one download
operationId: getDownload
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The job
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DownloadJob"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Downloads]
summary: Cancel a running download, or forget a finished one
description: >
A running job is asked to stop and reports `cancelling`; the task
notices between chunks, deletes its partial file and records the
outcome itself. A finished job's record is deleted.
The downloaded file is never removed. Deleting a job record is a
request to stop tracking it, not to lose a file that finished an hour
ago.
operationId: cancelDownload
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Cancelling, or the record was removed
"404":
$ref: "#/components/responses/NotFound"
/documents:
get:
tags: [Documents]
summary: List ingested documents
description: >
Newest first, without their content: a listing carrying every
document's full text would grow without bound and none of it is shown
in a list.
operationId: listDocuments
responses:
"200":
description: Documents
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/DocumentSummary"
post:
tags: [Documents]
summary: Ingest a document
description: >
Splits the content, embeds each piece and stores both, so the document
can afterwards be retrieved by meaning.
The whole ingestion is one transaction: a document whose chunks were
half written would list with a chunk count it does not have and return
partial answers to searches.
Needs an embedding model. With none configured this answers 503 naming
the variable rather than storing the document unindexed.
operationId: ingestDocument
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [title, content]
properties:
title:
type: string
content:
type: string
source:
type: string
description: Where the document came from. Defaults to `upload`.
docType:
type: string
description: Free-form type label. Defaults to `text`.
strategy:
type: string
description: >
How to split the content. Prose splits well on paragraphs
and source does not, so the choice is the caller's.
enum: [semantic, paragraph, sentence, fixed_size, code]
default: semantic
responses:
"200":
description: Document ingested
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DocumentSummary"
"400":
description: Title or content missing, content produced no chunks, or an unknown strategy
"502":
description: The embedding endpoint was unreachable or errored
"503":
description: No embedding model configured on the server
/documents/search:
get:
tags: [Documents]
summary: Rank stored chunks by meaning
description: >
Cosine similarity against the ingested chunks. Reports `searched`, the
number of chunks compared, so an empty knowledge base is
distinguishable from a query that matched nothing.
Chunks embedded under a different model are skipped rather than
compared: vectors from two models do not share a space, so the
similarity between them is a meaningless number that would still rank.
Never falls back to substring matching.
operationId: searchDocuments
parameters:
- name: q
in: query
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 10
maximum: 100
responses:
"200":
description: Ranked chunks
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DocumentSearchResults"
"400":
description: q is missing or empty
"502":
description: The embedding endpoint was unreachable or errored
"503":
description: No embedding model configured on the server
/documents/{id}:
get:
tags: [Documents]
summary: Get one document and its chunks
description: >
The vectors are not returned: they are large, unreadable, and nothing
on the other side has a use for them.
operationId: getDocument
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: The document
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/DocumentDetail"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Documents]
summary: Delete a document and its chunks
operationId: deleteDocument
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Document removed
"404":
$ref: "#/components/responses/NotFound"
/mcp/tools:
get:
tags: [MCP]
summary: List MCP tools
description: Tool definitions in OpenAI function-calling form, for use as chat tools.
operationId: listMcpTools
responses:
"200":
description: Tool definitions
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
mcp_tools:
type: array
items:
$ref: "#/components/schemas/McpTool"
tools:
type: array
items:
type: object
/mcp/system-prompt:
get:
tags: [MCP]
summary: System prompt describing the available tools
operationId: getMcpSystemPrompt
responses:
"200":
description: Prompt text and the tool list it describes
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
system_prompt:
type: string
available_tools:
type: array
items:
type: string
/mcp/call:
post:
tags: [MCP]
summary: Invoke one MCP tool
operationId: callMcpTool
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
name:
type: string
arguments:
type: object
responses:
"200":
description: Tool result
/mcp/batch:
post:
tags: [MCP]
summary: Invoke several MCP tools in one request
operationId: callMcpToolsBatch
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Tool results
/inbox/notifications:
get:
tags: [Inbox]
summary: List notifications
operationId: listNotifications
responses:
"200":
description: Notifications
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
type: object
/inbox/notifications/read-all:
post:
tags: [Inbox]
summary: Mark every notification read
operationId: markAllNotificationsRead
responses:
"200":
description: Marked
/inbox/notifications/{id}/dismiss:
post:
tags: [Inbox]
summary: Dismiss a notification
operationId: dismissNotification
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Dismissed
"404":
$ref: "#/components/responses/NotFound"
/inbox/messages:
get:
tags: [Inbox]
summary: List agent messages
operationId: listInboxMessages
responses:
"200":
description: Messages
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
type: object
/inbox/messages/{id}/read:
post:
tags: [Inbox]
summary: Mark a message read
operationId: markMessageRead
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Marked
"404":
$ref: "#/components/responses/NotFound"
/inbox/messages/{id}/archive:
post:
tags: [Inbox]
summary: Archive a message
operationId: archiveMessage
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Archived
"404":
$ref: "#/components/responses/NotFound"
/inbox/messages/{id}/respond:
post:
tags: [Inbox]
summary: Reply to an agent message
operationId: respondToMessage
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
response:
type: string
responses:
"200":
description: Response recorded
"404":
$ref: "#/components/responses/NotFound"
/inbox/permissions:
get:
tags: [Inbox]
summary: List permission requests
description: >
A request whose expiry has passed reads as `expired` rather than
`pending`; the status is derived on read, not written by a sweeper.
operationId: listPermissions
responses:
"200":
description: Permission requests
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
type: object
/inbox/workflows:
get:
tags: [Inbox]
summary: List workflow runs
operationId: listWorkflows
responses:
"200":
description: Workflow runs
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
type: object
/swe/projects:
get:
tags: [SWE]
summary: List SWE projects
operationId: listSweProjects
responses:
"200":
description: Projects
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/SweProject"
post:
tags: [SWE]
summary: Register a SWE project
description: The path must exist on disk; the server rejects one that does not.
operationId: createSweProject
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [name, path]
properties:
name:
type: string
path:
type: string
description:
type: string
responses:
"200":
description: Project registered
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SweProject"
/swe/projects/{id}:
get:
tags: [SWE]
summary: Get a SWE project
operationId: getSweProject
parameters:
- $ref: "#/components/parameters/sweProjectId"
responses:
"200":
description: Project
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SweProject"
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [SWE]
summary: Delete a SWE project
operationId: deleteSweProject
parameters:
- $ref: "#/components/parameters/sweProjectId"
responses:
"200":
description: Deleted
"404":
$ref: "#/components/responses/NotFound"
/swe/projects/{id}/open:
post:
tags: [SWE]
summary: Mark a project opened
description: Updates `lastOpened`.
operationId: openSweProject
parameters:
- $ref: "#/components/parameters/sweProjectId"
responses:
"200":
description: Recorded
/swe/projects/{id}/context:
get:
tags: [SWE]
summary: Assembled project context
description: Memory and rules for the project, plus a system-prompt fragment built from them.
operationId: getSweContext
parameters:
- $ref: "#/components/parameters/sweProjectId"
responses:
"200":
description: Context
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SweContext"
/swe/projects/{id}/execute:
post:
tags: [SWE]
summary: Execute a tool in the project
operationId: executeSweTool
parameters:
- $ref: "#/components/parameters/sweProjectId"
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Tool result
/swe/projects/{project_id}/memory:
get:
tags: [SWE]
summary: List project memory
operationId: listSweMemory
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
responses:
"200":
description: Memory entries
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/SweMemory"
post:
tags: [SWE]
summary: Store a memory entry
operationId: createSweMemory
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [key, value]
properties:
key:
type: string
value:
type: string
category:
type: string
importance:
type: string
responses:
"200":
description: Stored
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SweMemory"
/swe/projects/{project_id}/memory/{id}:
get:
tags: [SWE]
summary: Get a memory entry
operationId: getSweMemory
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
- $ref: "#/components/parameters/sweEntryId"
responses:
"200":
description: Memory entry
"404":
$ref: "#/components/responses/NotFound"
put:
tags: [SWE]
summary: Update a memory entry
operationId: updateSweMemory
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
- $ref: "#/components/parameters/sweEntryId"
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [SWE]
summary: Delete a memory entry
operationId: deleteSweMemory
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
- $ref: "#/components/parameters/sweEntryId"
responses:
"200":
description: Deleted
"404":
$ref: "#/components/responses/NotFound"
/swe/projects/{project_id}/rules:
get:
tags: [SWE]
summary: List project rules
operationId: listSweRules
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
responses:
"200":
description: Rules
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/SweRule"
post:
tags: [SWE]
summary: Add a rule
operationId: createSweRule
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [rule]
properties:
rule:
type: string
description:
type: string
category:
type: string
priority:
type: integer
responses:
"200":
description: Rule added
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SweRule"
/swe/projects/{project_id}/rules/{id}:
put:
tags: [SWE]
summary: Update a rule
operationId: updateSweRule
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
- $ref: "#/components/parameters/sweEntryId"
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [SWE]
summary: Delete a rule
operationId: deleteSweRule
parameters:
- $ref: "#/components/parameters/sweProjectIdAlt"
- $ref: "#/components/parameters/sweEntryId"
responses:
"200":
description: Deleted
"404":
$ref: "#/components/responses/NotFound"
/inbox:
get:
tags: [Inbox]
summary: Get the whole inbox
description: Notifications, agent messages, permission requests and workflow runs in one response.
operationId: getInbox
responses:
"200":
description: Inbox contents
/inbox/counts:
get:
tags: [Inbox]
summary: Unread and pending counts
description: Badge counts only; cheaper than fetching records to length-filter them.
operationId: getInboxCounts
responses:
"200":
description: Counts
/inbox/notifications/{id}/read:
post:
tags: [Inbox]
summary: Mark a notification read
operationId: markNotificationRead
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Marked read
"404":
description: No notification with that id
/inbox/messages/{id}/star:
post:
tags: [Inbox]
summary: Toggle a message's star
description: Toggles server-side, so concurrent viewers cannot disagree on the state.
operationId: toggleMessageStar
parameters:
- name: id
in: path
required: true
schema:
type: string
responses:
"200":
description: Toggled
"404":
description: No message with that id
/inbox/permissions/{id}/respond:
post:
tags: [Inbox]
summary: Approve or deny a permission request
description: >-
Expiry is applied on read, so a lapsed request reports `expired` rather
than staying approvable. Responding to one returns 409 instead of a
misleading success, because the agent that raised it has moved on.
operationId: respondToPermission
parameters:
- name: id
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [approved]
properties:
approved:
type: boolean
scope:
type: string
enum: [once, session, run, always]
note:
type: string
responses:
"200":
description: Recorded
"404":
description: No pending request with that id
"409":
description: The request expired before it was answered
/stats/timeline:
get:
tags: [Statistics]
summary: Sessions and messages per day
description: >
Days with no activity are omitted rather than zero-filled: the store
knows nothing about a day on which nothing happened.
operationId: getTimeline
parameters:
- name: days
in: query
schema:
type: integer
default: 30
minimum: 1
maximum: 365
responses:
"200":
description: Activity per day, oldest first
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
days:
type: integer
points:
type: array
items:
type: object
properties:
date:
type: string
format: date
sessions:
type: integer
messages:
type: integer
/sessions/merge:
post:
tags: [Sessions]
summary: Merge sessions into a new one
description: >
Concatenates the named sessions in order. The sources are left intact
-- a merge that consumed its inputs would make an accidental merge
unrecoverable. Each turn records `mergedFrom`.
operationId: mergeSessions
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [sessionIds]
properties:
sessionIds:
type: array
items:
type: string
minItems: 2
title:
type: string
responses:
"201":
description: Merged session created
"400":
description: Fewer than two sessions named
"404":
description: One of the named sessions does not exist
/sessions/{id}/fork:
post:
tags: [Sessions]
summary: Copy a session
description: >
The copy is independent; appending to either afterwards does not
affect the other. Records its origin in `parentSessionId`.
operationId: forkSession
parameters:
- $ref: "#/components/parameters/sessionId"
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
title:
type: string
responses:
"201":
description: Fork created
"404":
$ref: "#/components/responses/NotFound"
/sessions/{id}/export:
get:
tags: [Sessions]
summary: Download a session
description: Served as an attachment. Markdown renders the transcript; json returns the stored blob.
operationId: exportSession
parameters:
- $ref: "#/components/parameters/sessionId"
- name: format
in: query
schema:
type: string
enum: [json, markdown]
default: json
responses:
"200":
description: The session file
content:
application/json:
schema:
type: object
text/markdown:
schema:
type: string
"400":
description: Unsupported format
"404":
$ref: "#/components/responses/NotFound"
/sessions/{id}/share:
post:
tags: [Sharing]
summary: Create a share link
description: >
Returns a token granting read access to this session **through this
server**. Nothing is uploaded anywhere. The token is a bearer
credential: anyone holding it can read the session until it expires or
is revoked.
operationId: createShare
parameters:
- $ref: "#/components/parameters/sessionId"
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
expiresInHours:
type: integer
minimum: 1
description: Omit for a link that only revocation can close.
responses:
"201":
description: Link created
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/ShareLinkCreated"
"400":
description: expiresInHours was not positive
"404":
$ref: "#/components/responses/NotFound"
get:
tags: [Sharing]
summary: List a session's share links
description: Includes revoked and expired links, so they can be audited.
operationId: listShares
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Share links, newest first
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/ShareLink"
/shared/{token}:
get:
tags: [Sharing]
summary: Read a shared session
description: >
Requires no authentication -- the token is the credential. Answers 404
for a token that is unknown, revoked or expired alike, so a probe
cannot tell a closed link from a guess.
operationId: readShared
parameters:
- $ref: "#/components/parameters/shareToken"
responses:
"200":
description: The session, read-only
"404":
description: Unknown, revoked or expired
delete:
tags: [Sharing]
summary: Revoke a share link
description: Revokes rather than deletes, keeping the access record.
operationId: revokeShare
parameters:
- $ref: "#/components/parameters/shareToken"
responses:
"200":
description: Revoked
"404":
$ref: "#/components/responses/NotFound"
/search/semantic:
get:
tags: [Search]
summary: Rank indexed sessions by meaning
description: >
Cosine similarity against embedded sessions. Only searches what has
been indexed -- `searched` reports how many vectors that was, so an
empty index is distinguishable from no matches. Never falls back to
substring matching; `/search` is where that lives.
operationId: semanticSearch
parameters:
- name: q
in: query
required: true
schema:
type: string
- name: limit
in: query
schema:
type: integer
default: 10
maximum: 100
responses:
"200":
description: Ranked matches
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SemanticResults"
"400":
description: q is missing or empty
"502":
description: The embedding endpoint was unreachable or errored
"503":
description: No embedding model configured on the server
/search/semantic/index:
post:
tags: [Search]
summary: Embed sessions for semantic search
description: >
Explicit because it costs money and time proportional to the store's
size; a query never triggers one. Skips sessions already embedded for
the current model unless `force` is set. Reports partial progress if
the embedding endpoint fails mid-run.
operationId: buildSemanticIndex
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
limit:
type: integer
default: 200
maximum: 2000
description: How many of the most recently updated sessions to consider.
force:
type: boolean
default: false
responses:
"200":
description: Indexing finished
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
model:
type: string
indexed:
type: integer
"502":
description: The embedding endpoint was unreachable or errored
"503":
description: No embedding model configured on the server
/auth/register:
servers: &rootServer
- url: http://localhost:8787
description: Local development server (paths below the server root)
post:
tags: [Auth]
summary: Create an account
operationId: register
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password, display_name]
properties:
email:
type: string
password:
type: string
display_name:
type: string
responses:
"200":
description: Account created and signed in
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/AuthSession"
"400":
description: Invalid request or the email is already registered
/auth/login:
servers: *rootServer
post:
tags: [Auth]
summary: Sign in
operationId: login
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [email, password]
properties:
email:
type: string
password:
type: string
responses:
"200":
description: Signed in
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/AuthSession"
"401":
description: Invalid email or password
/auth/logout:
servers: *rootServer
post:
tags: [Auth]
summary: Sign out
operationId: logout
responses:
"200":
description: Signed out
/auth/refresh:
servers: *rootServer
post:
tags: [Auth]
summary: Exchange a refresh token for a new access token
operationId: refreshToken
requestBody:
required: true
content:
application/json:
schema:
type: object
required: [refresh_token]
properties:
refresh_token:
type: string
responses:
"200":
description: New tokens
"401":
description: Refresh token invalid or expired
/auth/profile:
servers: *rootServer
get:
tags: [Auth]
summary: Get the signed-in user
operationId: getProfile
responses:
"200":
description: The user
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/AuthUser"
"401":
description: Not authenticated
put:
tags: [Auth]
summary: Update the signed-in user
operationId: updateProfile
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
display_name:
type: string
avatar_url:
type: string
responses:
"200":
description: Updated
"401":
description: Not authenticated
/auth/password:
servers: *rootServer
put:
tags: [Auth]
summary: Change password
operationId: changePassword
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
current_password:
type: string
new_password:
type: string
responses:
"200":
description: Password changed
"401":
description: Not authenticated
/auth/subscription:
servers: *rootServer
get:
tags: [Auth]
summary: Get subscription state
operationId: getSubscription
responses:
"200":
description: Subscription
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/Subscription"
"401":
description: Not authenticated
/auth/subscription/upgrade:
servers: *rootServer
post:
tags: [Auth]
summary: Change subscription tier
operationId: upgradeSubscription
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
tier:
type: string
responses:
"200":
description: Tier changed
"401":
description: Not authenticated
/sync/version:
servers: *rootServer
get:
tags: [Sync]
summary: Current sync version
operationId: getSyncVersion
responses:
"200":
description: Version and event count
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
type: object
properties:
version:
type: integer
eventCount:
type: integer
/sync/delta:
servers: *rootServer
get:
tags: [Sync]
summary: Changes since a version
description: >
Note the mixed casing -- `from_version` and `to_version` are
snake_case where the rest of the payload is not. That is what the
server sends.
operationId: getSyncDelta
parameters:
- name: since
in: query
schema:
type: integer
responses:
"200":
description: Delta
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SyncDelta"
/sync/snapshot:
servers: *rootServer
get:
tags: [Sync]
summary: Full state snapshot
operationId: getSyncSnapshot
responses:
"200":
description: Snapshot
content:
application/json:
schema:
allOf:
- $ref: "#/components/schemas/ApiEnvelope"
- type: object
properties:
data:
$ref: "#/components/schemas/SyncSnapshot"
/sync/event:
servers: *rootServer
post:
tags: [Sync]
summary: Record one sync event
operationId: postSyncEvent
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Event recorded
/sync/batch:
servers: *rootServer
post:
tags: [Sync]
summary: Record several sync events
operationId: postSyncBatch
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Events recorded
/sync/subscribe:
servers: *rootServer
get:
tags: [Sync]
summary: Server-sent event stream of sync changes
description: >
An SSE stream, not a JSON document -- the response never completes
while the client stays connected.
operationId: subscribeSync
responses:
"200":
description: Event stream
content:
text/event-stream:
schema:
type: string
/recording/status:
servers: *rootServer
get:
tags: [Recording]
summary: Recorder status
description: This scope answers bare, without the `{success, data}` envelope.
operationId: getRecordingStatus
responses:
"200":
description: Status
content:
application/json:
schema:
$ref: "#/components/schemas/RecordingStatus"
/recording/sessions:
servers: *rootServer
get:
tags: [Recording]
summary: Sessions currently being recorded
operationId: listRecordingSessions
responses:
"200":
description: Active sessions
content:
application/json:
schema:
type: object
properties:
active_sessions:
type: array
items:
type: object
total:
type: integer
/recording/session/{id}:
servers: *rootServer
get:
tags: [Recording]
summary: A recorded session
operationId: getRecordingSession
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Recorded session
"404":
$ref: "#/components/responses/NotFound"
/recording/session/{id}/recovery:
servers: *rootServer
get:
tags: [Recording]
summary: Recovery data for a session
operationId: getRecordingRecovery
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Recovery data
"404":
$ref: "#/components/responses/NotFound"
/recording/events:
servers: *rootServer
post:
tags: [Recording]
summary: Record events
operationId: recordEvents
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Recorded
/recording/snapshot:
servers: *rootServer
post:
tags: [Recording]
summary: Store a recording snapshot
operationId: storeRecordingSnapshot
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Stored
/recording/ws:
servers: *rootServer
get:
tags: [Recording]
summary: WebSocket for live recording
description: >
A WebSocket upgrade, not an HTTP response. A plain GET without the
upgrade headers is rejected. Distinct from `/ws`, which carries
general real-time updates.
operationId: recordingWebSocket
responses:
"101":
description: Switching protocols
"400":
description: Not a WebSocket handshake
/webhooks:
servers: *rootServer
get:
tags: [Webhooks]
summary: List webhooks
description: This scope answers bare, without the `{success, data}` envelope.
operationId: listWebhooks
responses:
"200":
description: Webhooks
content:
application/json:
schema:
type: array
items:
type: object
post:
tags: [Webhooks]
summary: Register a webhook
operationId: createWebhook
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Registered
/webhooks/deliveries:
servers: *rootServer
get:
tags: [Webhooks]
summary: Delivery attempts across all webhooks
operationId: listAllDeliveries
responses:
"200":
description: Deliveries
content:
application/json:
schema:
type: array
items:
type: object
/webhooks/{id}:
servers: *rootServer
get:
tags: [Webhooks]
summary: Get a webhook
operationId: getWebhook
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Webhook
"404":
$ref: "#/components/responses/NotFound"
put:
tags: [Webhooks]
summary: Update a webhook
operationId: updateWebhook
parameters:
- $ref: "#/components/parameters/sessionId"
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Updated
"404":
$ref: "#/components/responses/NotFound"
delete:
tags: [Webhooks]
summary: Delete a webhook
operationId: deleteWebhook
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Deleted
"404":
$ref: "#/components/responses/NotFound"
/webhooks/{id}/test:
servers: *rootServer
post:
tags: [Webhooks]
summary: Send a test delivery
operationId: testWebhook
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Test dispatched
"404":
$ref: "#/components/responses/NotFound"
/webhooks/{id}/deliveries:
servers: *rootServer
get:
tags: [Webhooks]
summary: Delivery attempts for one webhook
operationId: listWebhookDeliveries
parameters:
- $ref: "#/components/parameters/sessionId"
responses:
"200":
description: Deliveries
"404":
$ref: "#/components/responses/NotFound"
/audit:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Audit]
summary: Query audit events
operationId: listAuditEvents
parameters:
- name: limit
in: query
required: false
description: Page size. Echoed back in the response.
schema:
type: integer
default: 100
- name: offset
in: query
required: false
schema:
type: integer
default: 0
responses:
"200":
description: A page of audit events
content:
application/json:
schema:
$ref: "#/components/schemas/AuditQueryResult"
/audit/{event_id}:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Audit]
summary: Get one audit event
operationId: getAuditEvent
parameters:
- name: event_id
in: path
required: true
schema:
type: string
responses:
"200":
description: The audit event
content:
application/json:
schema:
$ref: "#/components/schemas/AuditEvent"
"404":
description: No event with that id
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
/audit/user/{user_id}:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Audit]
summary: Audit events for one user
operationId: listAuditEventsForUser
parameters:
- name: user_id
in: path
required: true
schema:
type: string
- name: from
in: query
required: false
description: RFC 3339 lower bound. Ignored if unparseable.
schema:
type: string
format: date-time
- name: to
in: query
required: false
schema:
type: string
format: date-time
- name: limit
in: query
required: false
schema:
type: integer
responses:
"200":
description: >
Matching events, as a bare array -- not the paged object /audit
returns.
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AuditEvent"
/audit/resource/{type}/{id}:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Audit]
summary: Audit events for one resource
operationId: listAuditEventsForResource
parameters:
- name: type
in: path
required: true
schema:
type: string
- name: id
in: path
required: true
schema:
type: string
- name: limit
in: query
required: false
schema:
type: integer
responses:
"200":
description: Matching events, as a bare array
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AuditEvent"
/audit/export:
x-ironbridge-feature: enterprise
servers: *rootServer
post:
tags: [Audit]
summary: Export audit events
description: >
Takes the same filters as the query endpoint plus a `format`. The
response is a file download; its content type follows the format, so
this operation does not return JSON unless JSON was asked for.
operationId: exportAuditEvents
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/AuditExportRequest"
responses:
"200":
description: >
The export, as an attachment named `audit-log.export`.
headers:
Content-Disposition:
schema:
type: string
example: attachment; filename="audit-log.export"
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/AuditEvent"
text/csv:
schema:
type: string
example: |
id,timestamp,category,action,outcome,actor_id,actor_email,resource_type,resource_id,description,error
application/x-ndjson:
schema:
type: string
/retention/policies:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Retention]
summary: List retention policies
operationId: listRetentionPolicies
parameters:
- name: organization_id
in: query
required: false
schema:
type: string
responses:
"200":
description: The policies
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/RetentionPolicy"
post:
tags: [Retention]
summary: Create a retention policy
operationId: createRetentionPolicy
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateRetentionPolicyRequest"
responses:
"201":
description: The created policy
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
/retention/policies/{policy_id}:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [Retention]
summary: Get a retention policy
operationId: getRetentionPolicy
parameters:
- $ref: "#/components/parameters/retentionPolicyId"
responses:
"200":
description: The policy
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
"404":
description: No policy with that id
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
put:
tags: [Retention]
summary: Update a retention policy
description: >
A partial update: omitted fields keep their current value. Note that
`updated_at` is not advanced by this operation.
operationId: updateRetentionPolicy
parameters:
- $ref: "#/components/parameters/retentionPolicyId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateRetentionPolicyRequest"
responses:
"200":
description: The updated policy
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionPolicy"
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
delete:
tags: [Retention]
summary: Delete a retention policy
operationId: deleteRetentionPolicy
parameters:
- $ref: "#/components/parameters/retentionPolicyId"
responses:
"204":
description: Deleted. No body.
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
/retention/policies/{policy_id}/execute:
x-ironbridge-feature: enterprise
servers: *rootServer
post:
tags: [Retention]
summary: Run a retention policy now
description: >
Applies the policy's expiry actions immediately. Deletions are not
reversible. A disabled policy is refused with 400 rather than run.
operationId: executeRetentionPolicy
parameters:
- $ref: "#/components/parameters/retentionPolicyId"
responses:
"200":
description: What the run did
content:
application/json:
schema:
$ref: "#/components/schemas/RetentionExecutionResult"
"400":
description: >
The policy is disabled, or does not exist.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: Policy is disabled
/sso/metadata:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [SSO]
summary: SAML service-provider metadata
description: >
The `EntityDescriptor` to hand to an identity provider. The URLs in it
come from `IRONBRIDGE_PUBLIC_BASE_URL`; without that they fall back to the
bind address, which is usually not reachable from a browser.
operationId: getSsoMetadata
responses:
"200":
description: SP metadata
content:
application/xml:
schema:
type: string
example: |
<?xml version="1.0" encoding="UTF-8"?>
<EntityDescriptor
xmlns="urn:oasis:names:tc:SAML:2.0:metadata"
entityID="https://ironbridge.example.com/saml/metadata">
<SPSSODescriptor
AuthnRequestsSigned="false"
WantAssertionsSigned="true"
protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<NameIDFormat>urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress</NameIDFormat>
<AssertionConsumerService
Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
Location="https://ironbridge.example.com/api/sso/callback"
index="0"
isDefault="true"/>
</SPSSODescriptor>
</EntityDescriptor>
/sso/initiate:
x-ironbridge-feature: enterprise
servers: *rootServer
post:
tags: [SSO]
summary: Begin a SAML login
description: >
Supply either `idp_id` or `email_domain`; supplying neither is a 400.
The caller redirects the browser to `redirect_url`.
operationId: initiateSso
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/InitiateSsoRequest"
responses:
"200":
description: Where to send the browser
content:
application/json:
schema:
$ref: "#/components/schemas/InitiateSsoResponse"
"400":
description: Neither `idp_id` nor `email_domain` was given, or no IdP matched
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: Must provide either idp_id or email_domain
/sso/callback:
x-ironbridge-feature: enterprise
servers: *rootServer
post:
tags: [SSO]
summary: SAML assertion consumer
description: >
Receives the IdP's assertion as a form post, not JSON. The response is
verified and then re-parsed from only the bytes the signature covered,
which is what makes it resistant to XML Signature Wrapping.
A rejected assertion is a 400, not a 401.
operationId: ssoCallback
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
$ref: "#/components/schemas/SamlCallbackRequest"
responses:
"200":
description: The assertion verified; a session was established
content:
application/json:
schema:
$ref: "#/components/schemas/SsoSession"
"400":
description: >
The assertion was malformed, unsigned, expired, for another
audience, or from an unconfigured issuer. The message does not
distinguish these.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: No assertion in response
/sso/idps:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [SSO]
summary: List identity providers
operationId: listIdps
parameters:
- name: organization_id
in: query
required: false
schema:
type: string
responses:
"200":
description: The configured providers
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/SamlIdpConfig"
post:
tags: [SSO]
summary: Register an identity provider
operationId: createIdp
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateIdpRequest"
responses:
"201":
description: The registered provider
content:
application/json:
schema:
$ref: "#/components/schemas/SamlIdpConfig"
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
/sso/idps/{idp_id}:
x-ironbridge-feature: enterprise
servers: *rootServer
put:
tags: [SSO]
summary: Update an identity provider
operationId: updateIdp
parameters:
- $ref: "#/components/parameters/idpId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateIdpRequest"
responses:
"200":
description: The updated provider
content:
application/json:
schema:
$ref: "#/components/schemas/SamlIdpConfig"
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
delete:
tags: [SSO]
summary: Remove an identity provider
operationId: deleteIdp
parameters:
- $ref: "#/components/parameters/idpId"
responses:
"204":
description: Removed. No body.
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
/oidc/providers:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [OIDC]
summary: List OIDC providers
operationId: listOidcProviders
parameters:
- name: organization_id
in: query
required: false
schema:
type: string
responses:
"200":
description: The configured providers, without their client secrets
content:
application/json:
schema:
type: array
items:
$ref: "#/components/schemas/OidcProvider"
post:
tags: [OIDC]
summary: Register an OIDC provider
description: >
The issuer must be `https`, except on loopback. The JWKS fetched from
that origin supplies every key the login flow trusts, so a plaintext
issuer lets anyone on the path choose the signing keys.
operationId: createOidcProvider
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/CreateOidcProviderRequest"
responses:
"201":
description: The registered provider
content:
application/json:
schema:
$ref: "#/components/schemas/OidcProvider"
"400":
description: >
Missing `issuer`/`client_id`, or an issuer that is neither https
nor loopback.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: issuer must be https (loopback may use http for development)
/oidc/providers/{provider_id}:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [OIDC]
summary: Get an OIDC provider
operationId: getOidcProvider
parameters:
- $ref: "#/components/parameters/oidcProviderId"
responses:
"200":
description: The provider
content:
application/json:
schema:
$ref: "#/components/schemas/OidcProvider"
"404":
description: No provider with that id
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
put:
tags: [OIDC]
summary: Update an OIDC provider
operationId: updateOidcProvider
parameters:
- $ref: "#/components/parameters/oidcProviderId"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/UpdateOidcProviderRequest"
responses:
"200":
description: The updated provider
content:
application/json:
schema:
$ref: "#/components/schemas/OidcProvider"
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
delete:
tags: [OIDC]
summary: Remove an OIDC provider
operationId: deleteOidcProvider
parameters:
- $ref: "#/components/parameters/oidcProviderId"
responses:
"204":
description: Removed. No body.
"400":
$ref: "#/components/responses/EnterpriseBadRequest"
/oidc/login:
x-ironbridge-feature: enterprise
servers: *rootServer
post:
tags: [OIDC]
summary: Begin an OIDC login
description: >
Discovers the provider, builds the authorization URL, and stores the
pending login server-side. Send the browser to `authorization_url`.
The PKCE verifier and the nonce stay on the server; the caller only
ever sees the opaque `state`.
operationId: beginOidcLogin
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/BeginOidcLoginRequest"
responses:
"200":
description: Where to send the browser
content:
application/json:
schema:
$ref: "#/components/schemas/BeginOidcLoginResponse"
"400":
description: >
Neither `provider_id` nor `email_domain` was given, no provider
matched, the provider is disabled, or discovery failed.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: Must provide either provider_id or email_domain
/oidc/callback:
x-ironbridge-feature: enterprise
servers: *rootServer
get:
tags: [OIDC]
summary: OIDC redirect endpoint
description: >
Where the provider returns the browser. Redeems the code and, if the
ID token verifies, issues IronBridge tokens.
`state` is single-use: it is consumed on the first callback, so a
replayed one is refused. A login whose ID token carries no verified
email is refused too — an unverified address must not select an
account.
operationId: oidcCallback
x-ironbridge-probe: needs-prior-state
parameters:
- name: code
in: query
required: true
schema:
type: string
- name: state
in: query
required: true
description: The handle returned by `POST /oidc/login`.
schema:
type: string
responses:
"200":
description: >
Login succeeded; IronBridge tokens issued. The same shape
`POST /auth/login` returns, but bare rather than enveloped.
content:
application/json:
schema:
$ref: "#/components/schemas/AuthSession"
"400":
description: >
Unknown, expired or already-used state; a failed token exchange;
an ID token that does not verify; or an unverified email claim.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
example:
error: Unknown or already-used state
components:
parameters:
workspaceId:
name: id
in: path
required: true
schema:
type: string
format: uuid
sessionId:
name: id
in: path
required: true
schema:
type: string
agentId:
name: id
in: path
required: true
schema:
type: string
format: uuid
sweProjectId:
name: id
in: path
required: true
schema:
type: string
sweProjectIdAlt:
name: project_id
in: path
required: true
schema:
type: string
sweEntryId:
name: id
in: path
required: true
schema:
type: string
shareToken:
name: token
in: path
required: true
schema:
type: string
retentionPolicyId:
name: policy_id
in: path
required: true
schema:
type: string
idpId:
name: idp_id
in: path
required: true
schema:
type: string
oidcProviderId:
name: provider_id
in: path
required: true
schema:
type: string
limitParam:
name: limit
in: query
schema:
type: integer
minimum: 1
maximum: 100
default: 20
offsetParam:
name: offset
in: query
schema:
type: integer
minimum: 0
default: 0
responses:
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
EnterpriseBadRequest:
description: >
The operation was refused. The enterprise services answer 400 for a
bad body, a missing resource and a rejected credential alike, so the
status alone does not tell them apart.
content:
application/json:
schema:
$ref: "#/components/schemas/EnterpriseError"
schemas:
ApiEnvelope:
type: object
required: [success]
properties:
success:
type: boolean
data:
description: The payload. Absent on failure.
error:
type: string
nullable: true
CreateSession:
type: object
properties:
title:
type: string
provider:
type: string
workspaceId:
type: string
workspacePath:
type: string
model:
type: string
CreateMessage:
type: object
required: [content]
properties:
role:
type: string
enum: [user, assistant, system]
default: user
content:
type: string
modelId:
type: string
Checkpoint:
type: object
properties:
id:
type: string
sessionId:
type: string
name:
type: string
description:
type: string
nullable: true
messageId:
type: string
nullable: true
gitCommit:
type: string
nullable: true
gitBranch:
type: string
nullable: true
createdAt:
type: integer
format: int64
metadata:
type: object
nullable: true
CreateCheckpoint:
type: object
properties:
name:
type: string
description:
type: string
messageId:
type: string
gitCommit:
type: string
gitBranch:
type: string
metadata:
type: object
GitCommit:
type: object
properties:
hash:
type: string
shortHash:
type: string
message:
type: string
author:
type: string
email:
type: string
timestamp:
type: integer
format: int64
branch:
type: string
sessionId:
type: string
nullable: true
messageId:
type: string
nullable: true
SearchResult:
type: object
properties:
type:
type: string
enum: [session, message, workspace]
id:
type: string
title:
type: string
snippet:
type: string
sessionId:
type: string
provider:
type: string
workspaceId:
type: string
timestamp:
type: integer
format: int64
ProviderStats:
type: object
properties:
sessions:
type: integer
messages:
type: integer
tokens:
type: integer
UpdateSwarm:
type: object
properties:
name:
type: string
description:
type: string
orchestration:
type: string
agents:
type: array
items:
type: object
maxIterations:
type: integer
status:
type: string
ChatCompletionRequest:
type: object
required: [messages]
properties:
model:
type: string
messages:
type: array
items:
$ref: "#/components/schemas/ChatMessage"
temperature:
type: number
format: float
maxTokens:
type: integer
ChatMessage:
type: object
required: [role, content]
properties:
role:
type: string
enum: [user, assistant, system]
content:
type: string
ChatCompletionResponse:
type: object
properties:
id:
type: string
model:
type: string
content:
type: string
message:
$ref: "#/components/schemas/ChatMessage"
finishReason:
type: string
usage:
type: object
nullable: true
HarvestResult:
type: object
properties:
success:
type: boolean
sessionsImported:
type: integer
messagesImported:
type: integer
errors:
type: array
items:
type: string
warnings:
type: array
items:
type: string
Error:
type: object
properties:
error:
type: string
message:
type: string
code:
type: string
required: [error, message]
HealthResponse:
type: object
properties:
status:
type: string
example: ok
version:
type: string
example: 2.0.1
SystemInfo:
type: object
properties:
version:
type: string
status:
type: string
example: healthy
uptime:
type: integer
description: Seconds since the server started.
database:
type: object
properties:
path:
type: string
sizeBytes:
type: integer
features:
type: object
properties:
agents:
type: boolean
chat:
type: boolean
mcp:
type: boolean
swarms:
type: boolean
Workspace:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
path:
type: string
provider:
type: string
session_count:
type: integer
last_harvested:
type: string
format: date-time
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Session:
type: object
properties:
id:
type: string
title:
type: string
provider:
type: string
messageCount:
type: integer
workspaceId:
type: string
nullable: true
workspaceName:
type: string
nullable: true
createdAt:
type: integer
format: int64
description: Epoch seconds.
updatedAt:
type: integer
format: int64
description: Epoch seconds.
SessionList:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Session"
total:
type: integer
limit:
type: integer
offset:
type: integer
hasMore:
type: boolean
SessionDetail:
type: object
properties:
session:
$ref: "#/components/schemas/Session"
messages:
type: array
items:
$ref: "#/components/schemas/Message"
tool_invocations:
type: array
items:
type: object
file_changes:
type: array
items:
type: object
Message:
type: object
properties:
index:
type: integer
role:
type: string
enum: [user, assistant, system]
content:
type: string
content_raw:
type: string
created_at:
type: integer
format: int64
nullable: true
request_id:
type: string
nullable: true
model_id:
type: string
nullable: true
variable_data:
nullable: true
AuthUser:
type: object
properties:
id:
type: string
email:
type: string
display_name:
type: string
avatar_url:
type: string
nullable: true
email_verified:
type: boolean
subscription_tier:
type: string
subscription_expires_at:
type: integer
format: int64
nullable: true
features:
type: array
items:
type: string
created_at:
type: integer
format: int64
AuthSession:
type: object
properties:
access_token:
type: string
refresh_token:
type: string
expires_in:
type: integer
description: Seconds until the access token expires.
user:
$ref: "#/components/schemas/AuthUser"
Subscription:
type: object
properties:
tier:
type: string
isActive:
type: boolean
expiresAt:
type: integer
format: int64
nullable: true
features:
type: array
items:
type: string
SyncDelta:
type: object
properties:
from_version:
type: integer
to_version:
type: integer
created:
type: array
items:
type: object
updated:
type: array
items:
type: object
deleted:
type: array
items:
type: object
timestamp:
type: integer
format: int64
SyncSnapshot:
type: object
properties:
version:
type: integer
timestamp:
type: integer
format: int64
workspaces:
type: array
items:
type: object
sessions:
type: array
items:
type: object
agents:
type: array
items:
type: object
swarms:
type: array
items:
type: object
providers:
type: array
items:
type: object
RecordingStatus:
type: object
properties:
status:
type: string
active_sessions:
type: integer
dirty_sessions:
type: integer
config:
type: object
properties:
max_memory_messages:
type: integer
persist_interval_secs:
type: integer
session_timeout_secs:
type: integer
ShareLinkCreated:
type: object
properties:
token:
type: string
description: Bearer credential. 256 bits, hex encoded.
sessionId:
type: string
path:
type: string
description: Where to read it on this server.
createdAt:
type: integer
format: int64
expiresAt:
type: integer
format: int64
nullable: true
revoked:
type: boolean
note:
type: string
ShareLink:
type: object
properties:
token:
type: string
createdAt:
type: integer
format: int64
expiresAt:
type: integer
format: int64
nullable: true
status:
type: string
enum: [active, expired, revoked]
description: Derived on read, so a link past its expiry never reads as active.
accessCount:
type: integer
lastAccessed:
type: integer
format: int64
nullable: true
SemanticResults:
type: object
properties:
query:
type: string
model:
type: string
searched:
type: integer
description: How many vectors were compared. Zero means nothing is indexed.
results:
type: array
items:
type: object
properties:
type:
type: string
id:
type: string
title:
type: string
nullable: true
score:
type: number
format: float
description: Cosine similarity, -1 to 1.
SystemHealth:
type: object
properties:
status:
type: string
enum: [healthy, degraded]
version:
type: string
uptime:
type: integer
description: Seconds since the server started.
checks:
type: object
properties:
database:
type: string
enum: [ok, error]
api:
type: string
enum: [ok, error]
ProviderHealth:
type: object
properties:
providerId:
type: string
status:
type: string
enum: [connected, disconnected, error, unknown]
latency:
type: integer
nullable: true
description: Milliseconds. Null unless the provider answered.
lastChecked:
type: integer
format: int64
description: Epoch milliseconds.
error:
type: string
nullable: true
models:
type: array
items:
type: string
McpTool:
type: object
properties:
name:
type: string
description:
type: string
inputSchema:
type: object
description: JSON Schema for the tool's arguments.
SweProject:
type: object
properties:
id:
type: string
name:
type: string
path:
type: string
description:
type: string
nullable: true
gitRemote:
type: string
nullable: true
gitBranch:
type: string
nullable: true
language:
type: string
nullable: true
framework:
type: string
nullable: true
lastOpened:
type: integer
format: int64
description: Epoch milliseconds.
createdAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
memoryCount:
type: integer
ruleCount:
type: integer
sessionCount:
type: integer
SweMemory:
type: object
properties:
id:
type: string
projectId:
type: string
key:
type: string
value:
type: string
category:
type: string
importance:
type: string
source:
type: string
sourceMessageId:
type: string
nullable: true
expiresAt:
type: integer
format: int64
nullable: true
accessCount:
type: integer
lastAccessed:
type: integer
format: int64
nullable: true
createdAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
SweRule:
type: object
properties:
id:
type: string
projectId:
type: string
rule:
type: string
description:
type: string
nullable: true
category:
type: string
priority:
type: integer
enabled:
type: boolean
scope:
type: string
nullable: true
conditions:
nullable: true
createdAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
SweContext:
type: object
properties:
memory:
type: array
items:
$ref: "#/components/schemas/SweMemory"
rules:
type: array
items:
$ref: "#/components/schemas/SweRule"
memoryCount:
type: integer
ruleCount:
type: integer
systemPromptAddition:
type: string
WorkspaceList:
type: object
properties:
items:
type: array
items:
$ref: "#/components/schemas/Workspace"
total:
type: integer
limit:
type: integer
offset:
type: integer
hasMore:
type: boolean
ProviderAccount:
type: object
description: >
A stored provider credential. This is the whole of what the
`provider_accounts` table keeps -- there is no column for a token type,
an email, a scope list or an expiry, and the credential is not returned.
required: [id, provider, name, isDefault, createdAt, updatedAt]
properties:
id:
type: string
format: uuid
provider:
type: string
example: Anthropic
name:
type: string
description: Display name, derived from the provider on creation.
example: Anthropic Account
isDefault:
type: boolean
createdAt:
type: integer
format: int64
description: Milliseconds since the Unix epoch.
updatedAt:
type: integer
format: int64
description: Milliseconds since the Unix epoch.
SwarmAgent:
type: object
description: >
One agent's membership of a swarm. The field is `agent_id`, not
`agentId`: the struct carries no serde rename.
required: [agent_id, role]
properties:
agent_id:
type: string
role:
type: string
example: coordinator
Note:
type: object
description: >
One clipping: text selected in a page and saved by the browser
extension.
required: [id, content, createdAt]
properties:
id:
type: string
content:
type: string
description: The selected text, as it was selected.
source:
type: string
description: The hostname of the page. Absent when the client sent none.
example: arxiv.org
url:
type: string
description: Absent when the client sent none.
capturedAt:
type: string
description: >
The client's clock when it captured the selection, verbatim. Not
parsed and not authoritative; absent when the client sent none.
createdAt:
type: integer
format: int64
description: When this server wrote the row, in milliseconds since the epoch.
Paper:
type: object
description: >
One arXiv entry.
There is deliberately no `citations`, `views`, `comments`, `stars` or
`trendScore`. arXiv's API reports none of them, and the pages this
replaced showed all five and ranked a leaderboard by them.
required: [arxivId, title, authors, summary, categories, published, url]
properties:
arxivId:
type: string
example: 2201.00978v1
title:
type: string
authors:
type: array
items:
type: string
summary:
type: string
description: The abstract, unwrapped — arXiv hard-wraps it at the source.
categories:
type: array
items:
type: string
example: [cs.CV, cs.LG]
published:
type: string
updated:
type: string
url:
type: string
description: The abstract page.
pdfUrl:
type: string
description: Absent when the entry links no PDF.
comment:
type: string
description: The authors' own note, e.g. a venue. Often absent.
PaperResults:
type: object
required: [query, source, totalResults, start, results]
properties:
query:
type: string
source:
type: string
enum: [arxiv]
totalResults:
type: integer
description: arXiv's own count for the query, not this page's length.
start:
type: integer
results:
type: array
items:
$ref: "#/components/schemas/Paper"
RepoFile:
type: object
required: [path, size]
properties:
path:
type: string
description: Path within the repository. May contain `/`.
size:
type: integer
format: int64
description: Bytes, as the Hub reports them — the real size for LFS files.
DatasetProblem:
type: object
required: [message]
properties:
entryIndex:
type: integer
description: Which entry is at fault. Absent for a whole-dataset problem.
message:
type: string
DatasetValidation:
type: object
required: [datasetId, datasetName, entryCount, usable, problems]
properties:
datasetId:
type: string
datasetName:
type: string
entryCount:
type: integer
usable:
type: boolean
description: True when `problems` is empty.
problems:
type: array
items:
$ref: "#/components/schemas/DatasetProblem"
TrainingJob:
type: object
description: >
A fine-tuning job at a provider.
There is deliberately no `progress`, `eta`, `gpu`, `accuracy` or `f1`.
A fine-tuning API reports none of them, and the tables this replaced
showed all five — including jobs 67% through work that had never
started.
required:
[id, providerJobId, datasetId, datasetName, baseModel, status, createdAt, updatedAt]
properties:
id:
type: string
providerJobId:
type: string
description: The provider's own id, so the job can be found in their dashboard.
datasetId:
type: string
datasetName:
type: string
baseModel:
type: string
status:
type: string
description: The provider's status verbatim — never derived or simulated.
enum: [validating_files, queued, running, succeeded, failed, cancelled]
fineTunedModel:
type: string
description: The resulting model's name, once the provider reports one.
trainedTokens:
type: integer
format: int64
error:
type: string
description: The provider's failure message.
createdAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
finishedAt:
type: integer
format: int64
refreshError:
type: string
description: >
Present when the provider could not be reached on this request,
meaning `status` is the last one successfully read rather than the
current one.
DownloadJob:
type: object
required:
[
id,
kind,
repoId,
filePath,
destPath,
totalBytes,
downloadedBytes,
status,
startedAt,
updatedAt,
]
properties:
id:
type: string
kind:
type: string
enum: [models, datasets]
repoId:
type: string
filePath:
type: string
destPath:
type: string
description: Absolute path on the server, so a user can find the file.
totalBytes:
type: integer
format: int64
description: From the Hub's file listing, read before the transfer started.
downloadedBytes:
type: integer
format: int64
description: >
Written periodically by the running transfer, so it lags the true
figure by at most a few megabytes.
status:
type: string
enum: [running, completed, failed, cancelled]
error:
type: string
description: Present on `failed`.
startedAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
completedAt:
type: integer
format: int64
CatalogResults:
type: object
required: [query, source, results]
properties:
query:
type: string
source:
type: string
enum: [huggingface]
results:
type: array
items:
$ref: "#/components/schemas/CatalogEntry"
CatalogEntry:
type: object
description: >
One row as the Hub publishes it.
There is deliberately no `size`, `samples`, `params`, `format` or
`downloaded` field. The Hub's search API reports none of them, and the
tables this replaced rendered all five as measurements -- "12.5 GB",
"4.2M samples", "GGUF" -- for artifacts nothing had measured.
required: [id, name, downloads, likes, tags, url, gated]
properties:
id:
type: string
description: Full Hub id.
example: meta-llama/Llama-3.1-8B-Instruct
author:
type: string
description: Absent for canonical, unnamespaced ids such as `gpt2`.
name:
type: string
downloads:
type: integer
format: int64
likes:
type: integer
format: int64
task:
type: string
description: Models only, e.g. `text-generation`.
library:
type: string
description: Models only, e.g. `transformers`.
description:
type: string
description: Datasets only, and often long.
tags:
type: array
description: >
Trimmed to what a reader can use; the Hub's bookkeeping tags
(`region:`, `arxiv:`, `base_model:`, and similar) are dropped.
items:
type: string
updatedAt:
type: string
description: >
ISO-8601, straight from the Hub. Absent rather than defaulted when
the row carries no date.
url:
type: string
description: Canonical Hub page, so clients link out rather than build the URL.
gated:
type: boolean
description: Whether the Hub requires accepting terms before the files are readable.
Dataset:
type: object
required:
[id, name, type, format, entryCount, sizeBytes, createdAt, updatedAt]
properties:
id:
type: string
name:
type: string
type:
type: string
enum: [conversations, documents, qa, custom]
format:
type: string
entryCount:
type: integer
description: Counted from the rows written, never taken from the request.
sizeBytes:
type: integer
format: int64
description: >
Summed over the stored JSON, so it describes what is on disk rather
than what the uploader claimed.
createdAt:
type: integer
format: int64
updatedAt:
type: integer
format: int64
DatasetEntryPage:
type: object
required: [datasetId, total, limit, offset, entries]
properties:
datasetId:
type: string
total:
type: integer
description: >
The dataset's whole record count, so a short last page is
distinguishable from an empty dataset.
limit:
type: integer
offset:
type: integer
entries:
type: array
description: The records as JSON, in the order they were uploaded.
items: {}
DocumentSummary:
type: object
required:
[
id,
title,
source,
docType,
chunkCount,
tokenCount,
embeddingModel,
chunkingStrategy,
createdAt,
]
properties:
id:
type: string
title:
type: string
source:
type: string
docType:
type: string
chunkCount:
type: integer
tokenCount:
type: integer
description: Estimated, summed over the document's chunks.
embeddingModel:
type: string
description: >
The model the chunks were embedded with. Search compares only
against chunks embedded under the model currently configured.
chunkingStrategy:
type: string
enum: [semantic, paragraph, sentence, fixed_size, code]
createdAt:
type: integer
format: int64
DocumentDetail:
allOf:
- $ref: "#/components/schemas/DocumentSummary"
- type: object
properties:
content:
type: string
chunks:
type: array
items:
type: object
properties:
index:
type: integer
content:
type: string
tokenCount:
type: integer
DocumentSearchResults:
type: object
required: [query, searched, results]
properties:
query:
type: string
searched:
type: integer
description: >
How many chunks were compared. Zero means nothing has been
ingested under the current embedding model, which is a different
answer from no matches.
results:
type: array
items:
type: object
properties:
documentId:
type: string
documentTitle:
type: string
chunkIndex:
type: integer
content:
type: string
score:
type: number
format: float
Provider:
type: object
description: >
An entry in the compiled-in provider catalogue. Every field but
`enabled` is static: the catalogue cannot be edited over the API.
required: [id, name, type, status, icon, color, models, enabled]
properties:
id:
type: string
description: Catalogue id, also the path parameter for updateProvider.
example: ollama
name:
type: string
example: Ollama
type:
type: string
description: >
Whether the provider runs on the user's own machine (`local`) or is
reached over the network (`cloud`). Clients should use this rather
than inferring it from the id.
enum: [cloud, local]
status:
type: string
description: >
The catalogue's declared status. This is not a probe result -- for
a measured answer use `/system/providers/health`.
enum: [connected, disconnected]
icon:
type: string
description: Emoji used as the provider's glyph.
example: "🦙"
color:
type: string
description: Brand colour as a hex triplet.
example: "#000000"
endpoint:
type: string
description: >
Base URL, omitted for providers that declare none. Note the name:
this field is `endpoint`, not `base_url`.
example: http://localhost:11434
models:
type: array
items:
type: string
enabled:
type: boolean
description: >
Whether the user has switched this provider on. Defaults to true
and is persisted per id by updateProvider.
Agent:
type: object
properties:
id:
type: string
format: uuid
name:
type: string
description:
type: string
system_prompt:
type: string
provider_id:
type: string
model:
type: string
temperature:
type: number
created_at:
type: string
format: date-time
CreateAgent:
type: object
properties:
name:
type: string
description:
type: string
system_prompt:
type: string
provider_id:
type: string
model:
type: string
temperature:
type: number
default: 0.7
required: [name, provider_id, model]
UpdateAgent:
type: object
properties:
name:
type: string
description:
type: string
system_prompt:
type: string
model:
type: string
temperature:
type: number
StatsOverview:
type: object
properties:
totalSessions:
type: integer
totalMessages:
type: integer
totalWorkspaces:
type: integer
totalToolInvocations:
type: integer
totalFileChanges:
type: integer
tablesEnhanced:
type: boolean
description: Whether the enhanced harvest tables are present.
sessionsByProvider:
type: array
items:
type: object
properties:
provider:
type: string
count:
type: integer
Settings:
type: object
properties:
theme:
type: string
enum: [light, dark, system]
autoSync:
type: boolean
syncInterval:
type: integer
description: Milliseconds between syncs.
defaultProvider:
type: string
enableNotifications:
type: boolean
compactMode:
type: boolean
maxHistoryDays:
type: integer
EnterpriseError:
type: object
required: [error]
properties:
error:
type: string
description: A human-readable message. Not a stable machine code.
example:
error: Policy not found
AuditCategory:
type: string
enum:
- authentication
- authorization
- user_management
- session_management
- workspace_management
- team_management
- configuration
- data_transfer
- administration
- system
- api_access
- sso
AuditOutcome:
type: string
enum: [success, failure, partial, denied, error]
AuditAction:
type: string
enum:
- login
- login_failed
- logout
- token_refresh
- password_change
- password_reset
- mfa_enabled
- mfa_disabled
- access_granted
- access_denied
- permission_changed
- user_created
- user_updated
- user_deleted
- user_suspended
- user_activated
- user_invited
- invite_accepted
- subscription_changed
- session_harvested
- session_viewed
- session_exported
- session_deleted
- session_archived
- session_shared
- session_unshared
- bulk_export
- bulk_delete
- workspace_created
- workspace_updated
- workspace_deleted
- workspace_linked
- workspace_unlinked
- team_created
- team_updated
- team_deleted
- member_added
- member_removed
- role_changed
- settings_updated
- provider_configured
- provider_disabled
- idp_configured
- idp_updated
- idp_deleted
- data_exported
- data_imported
- backup_created
- backup_restored
- admin_action_performed
- system_config_changed
- retention_policy_applied
- data_purged
- service_started
- service_stopped
- error_occurred
- maintenance_started
- maintenance_completed
- sso_login_initiated
- sso_login_completed
- sso_login_failed
- slo_initiated
- slo_completed
- created
- updated
- deleted
- viewed
- listed
- searched
AuditActor:
type: object
required: [user_id, email]
properties:
user_id:
type: string
email:
type: string
display_name:
type: string
nullable: true
tier:
type: string
nullable: true
auth_method:
type: string
nullable: true
description: password, sso, api_key, ...
session_id:
type: string
nullable: true
AuditResource:
type: object
required: [resource_type, resource_id]
properties:
resource_type:
type: string
resource_id:
type: string
name:
type: string
nullable: true
parent:
allOf:
- $ref: "#/components/schemas/AuditResource"
nullable: true
description: The containing resource, e.g. the workspace of a session.
AuditRequest:
type: object
required: [method, path, request_id]
properties:
method:
type: string
path:
type: string
query:
type: string
nullable: true
ip_address:
type: string
nullable: true
user_agent:
type: string
nullable: true
request_id:
type: string
status_code:
type: integer
nullable: true
duration_ms:
type: integer
nullable: true
AuditEvent:
type: object
required:
[id, timestamp, category, action, outcome, details, description, tags]
properties:
id:
type: string
timestamp:
type: string
format: date-time
category:
$ref: "#/components/schemas/AuditCategory"
action:
$ref: "#/components/schemas/AuditAction"
outcome:
$ref: "#/components/schemas/AuditOutcome"
actor:
allOf:
- $ref: "#/components/schemas/AuditActor"
nullable: true
description: Absent for unauthenticated and system-originated events.
resource:
allOf:
- $ref: "#/components/schemas/AuditResource"
nullable: true
request:
allOf:
- $ref: "#/components/schemas/AuditRequest"
nullable: true
details:
type: object
additionalProperties: true
description:
type: string
error:
type: string
nullable: true
organization_id:
type: string
nullable: true
correlation_id:
type: string
nullable: true
tags:
type: array
items:
type: string
AuditQueryResult:
type: object
required: [events, total, offset, limit, has_more]
properties:
events:
type: array
items:
$ref: "#/components/schemas/AuditEvent"
total:
type: integer
offset:
type: integer
limit:
type: integer
has_more:
type: boolean
example:
events: []
total: 0
offset: 0
limit: 100
has_more: false
AuditExportRequest:
type: object
description: >
The audit query filters, flattened, plus the output format. Every
field is optional; an empty object exports everything as JSON.
properties:
format:
type: string
enum: [json, csv, jsonlines]
default: json
category:
$ref: "#/components/schemas/AuditCategory"
action:
$ref: "#/components/schemas/AuditAction"
outcome:
$ref: "#/components/schemas/AuditOutcome"
actor_id:
type: string
actor_email:
type: string
resource_type:
type: string
resource_id:
type: string
organization_id:
type: string
correlation_id:
type: string
search:
type: string
description: Substring match against the description.
from:
type: string
format: date-time
to:
type: string
format: date-time
tags:
type: array
items:
type: string
offset:
type: integer
limit:
type: integer
ResourceType:
type: string
enum:
- session
- workspace
- audit_log
- user
- export
- temp_file
- backup
- api_log
- analytics
ExpiryAction:
type: string
enum:
- delete
- archive
- soft_delete
- anonymize
- export_before_delete
- notify_owner
RetentionCondition:
type: object
description: Tagged by `type`.
required: [type]
properties:
type:
type: string
enum:
[always, age, has_tag, status, metadata_match, and, or]
field:
type: string
description: >
For `age`, the timestamp to measure from: created_at, updated_at,
last_accessed_at, archived_at or deleted_at. For `metadata_match`,
the metadata key.
tag:
type: string
status:
type: string
value:
type: string
conditions:
type: array
description: Operands of `and` / `or`.
items:
$ref: "#/components/schemas/RetentionCondition"
RetentionPeriod:
type: object
description: Tagged by `type`.
required: [type]
properties:
type:
type: string
enum: [forever, duration, until, compliance_archive]
days:
type: integer
description: For `duration`.
date:
type: string
format: date-time
description: For `until`.
active_days:
type: integer
description: For `compliance_archive`.
archive_days:
type: integer
description: For `compliance_archive`.
RetentionRule:
type: object
required: [name, condition, retention_period, priority]
properties:
name:
type: string
condition:
$ref: "#/components/schemas/RetentionCondition"
retention_period:
$ref: "#/components/schemas/RetentionPeriod"
priority:
type: integer
description: Higher is evaluated first.
RetentionSchedule:
type: object
description: Tagged by `type`.
required: [type]
properties:
type:
type: string
enum: [manual, interval, daily, weekly, monthly]
hours:
type: integer
description: For `interval`.
day:
type: integer
description: >
For `weekly`, 0 (Sunday) to 6. For `monthly`, 1 to 28.
hour:
type: integer
minute:
type: integer
RetentionPolicy:
type: object
required:
- id
- name
- enabled
- resource_types
- rules
- schedule
- expiry_actions
- created_at
- updated_at
properties:
id:
type: string
format: uuid
name:
type: string
description:
type: string
nullable: true
enabled:
type: boolean
organization_id:
type: string
nullable: true
description: Null means the policy is global.
resource_types:
type: array
items:
$ref: "#/components/schemas/ResourceType"
rules:
type: array
items:
$ref: "#/components/schemas/RetentionRule"
schedule:
$ref: "#/components/schemas/RetentionSchedule"
expiry_actions:
type: array
items:
$ref: "#/components/schemas/ExpiryAction"
created_at:
type: integer
format: int64
description: Unix seconds.
updated_at:
type: integer
format: int64
last_run_at:
type: integer
format: int64
nullable: true
next_run_at:
type: integer
format: int64
nullable: true
description: Null when the schedule is `manual`.
CreateRetentionPolicyRequest:
type: object
required: [name, resource_types, rules, schedule, expiry_actions]
properties:
name:
type: string
description:
type: string
enabled:
type: boolean
default: true
organization_id:
type: string
resource_types:
type: array
items:
$ref: "#/components/schemas/ResourceType"
rules:
type: array
items:
$ref: "#/components/schemas/RetentionRule"
schedule:
$ref: "#/components/schemas/RetentionSchedule"
expiry_actions:
type: array
items:
$ref: "#/components/schemas/ExpiryAction"
example:
name: Ninety day sessions
resource_types: [session]
rules:
- name: age
condition: { type: age, field: created_at }
retention_period: { type: duration, days: 90 }
priority: 10
schedule: { type: daily, hour: 3, minute: 30 }
expiry_actions: [delete]
UpdateRetentionPolicyRequest:
type: object
description: Every field optional; omitted fields are left alone.
properties:
name:
type: string
description:
type: string
enabled:
type: boolean
resource_types:
type: array
items:
$ref: "#/components/schemas/ResourceType"
rules:
type: array
items:
$ref: "#/components/schemas/RetentionRule"
schedule:
$ref: "#/components/schemas/RetentionSchedule"
expiry_actions:
type: array
items:
$ref: "#/components/schemas/ExpiryAction"
RetentionStats:
type: object
properties:
scanned:
type: integer
expired:
type: integer
deleted:
type: integer
archived:
type: integer
anonymized:
type: integer
soft_deleted:
type: integer
exported:
type: integer
notified:
type: integer
failed:
type: integer
skipped:
type: integer
bytes_freed:
type: integer
format: int64
RetentionActionLog:
type: object
required: [resource_type, resource_id, action, success, timestamp]
properties:
resource_type:
$ref: "#/components/schemas/ResourceType"
resource_id:
type: string
action:
$ref: "#/components/schemas/ExpiryAction"
success:
type: boolean
error:
type: string
nullable: true
timestamp:
type: string
format: date-time
RetentionExecutionResult:
type: object
required:
- execution_id
- policy_id
- started_at
- completed_at
- success
- stats
- total_processed
- total_affected
- total_failed
- actions_taken
properties:
execution_id:
type: string
policy_id:
type: string
started_at:
type: string
format: date-time
completed_at:
type: string
format: date-time
success:
type: boolean
error:
type: string
nullable: true
stats:
type: object
description: Keyed by resource type.
additionalProperties:
$ref: "#/components/schemas/RetentionStats"
total_processed:
type: integer
total_affected:
type: integer
total_failed:
type: integer
actions_taken:
type: array
items:
$ref: "#/components/schemas/RetentionActionLog"
AttributeMappings:
type: object
description: >
Which SAML assertion attribute supplies each user field. Note that
`email` and `display_name` default to the empty string rather than to
a conventional attribute name, so an IdP created without them supplies
neither.
required: [email, display_name]
properties:
email:
type: string
display_name:
type: string
first_name:
type: string
nullable: true
last_name:
type: string
nullable: true
groups:
type: string
nullable: true
department:
type: string
nullable: true
SamlIdpConfig:
type: object
required:
- id
- name
- entity_id
- sso_url
- certificate
- enabled
- domains
- attribute_mappings
- default_tier
- auto_provision
- created_at
- updated_at
properties:
id:
type: string
format: uuid
name:
type: string
entity_id:
type: string
sso_url:
type: string
slo_url:
type: string
nullable: true
certificate:
type: string
description: >
The IdP's X.509 signing certificate. Returned as stored -- this is
public key material, but the endpoint is admin-only regardless.
enabled:
type: boolean
domains:
type: array
description: >
Email domains routed to this IdP. An IdP with none can only be
reached by explicit id.
items:
type: string
organization_id:
type: string
nullable: true
attribute_mappings:
$ref: "#/components/schemas/AttributeMappings"
default_tier:
type: string
description: Subscription tier granted to auto-provisioned users.
auto_provision:
type: boolean
created_at:
type: integer
format: int64
updated_at:
type: integer
format: int64
CreateIdpRequest:
type: object
required: [name, entity_id, sso_url, certificate]
properties:
name:
type: string
entity_id:
type: string
sso_url:
type: string
slo_url:
type: string
certificate:
type: string
organization_id:
type: string
attribute_mappings:
$ref: "#/components/schemas/AttributeMappings"
auto_provision:
type: boolean
domains:
type: array
items:
type: string
UpdateIdpRequest:
type: object
description: >
Every field optional. `entity_id` and `domains` are not updatable.
properties:
name:
type: string
sso_url:
type: string
slo_url:
type: string
certificate:
type: string
enabled:
type: boolean
attribute_mappings:
$ref: "#/components/schemas/AttributeMappings"
auto_provision:
type: boolean
InitiateSsoRequest:
type: object
description: Supply `idp_id` or `email_domain`. Neither is a 400.
properties:
idp_id:
type: string
email_domain:
type: string
description: Resolved against each IdP's `domains`.
relay_state:
type: string
description: Round-tripped through the IdP; typically a return path.
InitiateSsoResponse:
type: object
required: [redirect_url, request_id]
properties:
redirect_url:
type: string
description: >
The IdP's SSO URL with the deflated, base64, URL-encoded
`SAMLRequest` and the `RelayState` attached.
request_id:
type: string
description: The AuthnRequest ID, echoed by the IdP as InResponseTo.
SamlCallbackRequest:
type: object
description: A form post from the IdP, not JSON.
required: [SAMLResponse]
properties:
SAMLResponse:
type: string
description: The base64 SAML Response.
RelayState:
type: string
SsoSession:
type: object
required: [id, user_id, idp_id, name_id, created_at, expires_at]
properties:
id:
type: string
user_id:
type: string
idp_id:
type: string
name_id:
type: string
description: The Subject NameID the IdP asserted.
session_index:
type: string
nullable: true
description: Needed to single-logout this session.
created_at:
type: integer
format: int64
expires_at:
type: integer
format: int64
OidcProvider:
type: object
description: >
An OIDC provider as returned over HTTP. The `client_secret` is never
included -- it is a credential that would let its holder impersonate
this application to the identity provider. `has_client_secret` says
whether one is configured, which is all a caller needs.
required:
- id
- name
- issuer
- client_id
- has_client_secret
- redirect_uri
- scopes
- enabled
- domains
- default_tier
- auto_provision
- created_at
- updated_at
properties:
id:
type: string
format: uuid
name:
type: string
issuer:
type: string
description: Trailing slash stripped on creation.
client_id:
type: string
has_client_secret:
type: boolean
redirect_uri:
type: string
scopes:
type: array
description: Empty means `openid email profile`.
items:
type: string
groups_claim:
type: string
nullable: true
description: Entra uses `groups`; others use `roles`.
enabled:
type: boolean
domains:
type: array
description: >
Email domains routed here, folded to lower case. A provider with
none is reachable only by explicit id.
items:
type: string
organization_id:
type: string
nullable: true
default_tier:
type: string
description: Tier granted to auto-provisioned users.
auto_provision:
type: boolean
description: >
Whether a first-time user is created. With this off, a login by
someone with no existing account is refused.
created_at:
type: integer
format: int64
updated_at:
type: integer
format: int64
CreateOidcProviderRequest:
type: object
required: [name, issuer, client_id, redirect_uri]
properties:
name:
type: string
issuer:
type: string
description: Must be https, except on loopback.
client_id:
type: string
client_secret:
type: string
description: Omit for a public client using PKCE alone.
redirect_uri:
type: string
scopes:
type: array
items:
type: string
groups_claim:
type: string
domains:
type: array
items:
type: string
organization_id:
type: string
auto_provision:
type: boolean
default: false
enabled:
type: boolean
default: true
example:
name: Entra
issuer: https://login.example.com/v2.0
client_id: client-abc
redirect_uri: https://ironbridge.example.com/oidc/callback
domains: [example.com]
auto_provision: true
UpdateOidcProviderRequest:
type: object
description: >
Every field optional; omitted fields are left alone. Sending
`client_secret` replaces the stored one — there is deliberately no way
to express "clear it" here, so that clearing cannot be confused with
omitting.
properties:
name:
type: string
client_id:
type: string
client_secret:
type: string
redirect_uri:
type: string
scopes:
type: array
items:
type: string
groups_claim:
type: string
enabled:
type: boolean
auto_provision:
type: boolean
domains:
type: array
items:
type: string
BeginOidcLoginRequest:
type: object
description: Supply `provider_id` or `email_domain`. Neither is a 400.
properties:
provider_id:
type: string
email_domain:
type: string
description: Matched against each provider's `domains`.
return_to:
type: string
description: Where to send the browser once the login completes.
BeginOidcLoginResponse:
type: object
required: [authorization_url, state]
properties:
authorization_url:
type: string
description: >
The provider's authorization endpoint with the PKCE challenge,
nonce and state attached.
state:
type: string
description: >
Opaque single-use handle. The PKCE verifier and nonce it stands
for stay on the server and are never sent to the browser.