API
Programmatic access to strategies, portfolios, assets, liabilities, simulations, and briefs. Same evaluation engine as the web app, CLI, and MCP tools.
API requests require an active Kova subscription and a Bearer token in the Authorization header. Generate a token from Settings in the web app, or use the CLI browser auth flow.
Authorization: Bearer kova_tk_xxxxxxxxxxxxxxxxxxxx curl https://kovatools.com/api/v1/strategies \ -H "Authorization: Bearer kova_tk_xxxxxxxxxxxxxxxxxxxx"
Every success response wraps the resource in a named key plus a meta object. Errors return an error object and the same meta shape.
{
"strategy": { "...": "..." },
"meta": {
"request_id": "abc-123",
"timestamp": "2026-02-15T12:00:00Z"
}
}
/api/v1/strategies
Returns all strategies owned by the authenticated user, including latest alignment fields when available.
/api/v1/strategies
Creates a strategy from a name and full strategy content.
/api/v1/strategies/:uuid
Returns full strategy content and metadata.
/api/v1/strategies/:uuid
Updates the name, content, or both.
/api/v1/strategies/:uuid
Deletes the strategy. Associated briefs are preserved but unlinked.
/api/v1/strategies/:uuid/versions
Lists saved version snapshots for a strategy.
/api/v1/strategies/:uuid/versions/:version_number
Returns the full content for a specific strategy version.
/api/v1/strategies/:uuid/versions/:version_number/restore
Restores a previous version while preserving the current content as a new version.
/api/v1/strategies/:uuid/portfolio
Returns the most recent composed portfolio: normalized holdings, manual assets and liabilities with UUIDs, and metrics.
/api/v1/strategies/:uuid/assets
Registers a non-ticker asset such as an investment account, Bitcoin, real estate, or other holding.
/api/v1/strategies/:uuid/assets/:asset_uuid
Updates provided asset fields with merge semantics.
/api/v1/strategies/:uuid/assets/:asset_uuid
Removes a manual asset from the strategy.
/api/v1/strategies/:uuid/liabilities
Registers a persistent obligation such as a line of credit, mortgage, loan, or other debt.
/api/v1/strategies/:uuid/liabilities/:liability_uuid
Updates provided liability fields with merge semantics.
/api/v1/strategies/:uuid/liabilities/:liability_uuid
Removes a manual liability from the strategy.
/api/v1/strategies/:uuid/briefs
Submits a portfolio snapshot or regenerates against existing portfolio data and starts asynchronous brief generation.
/api/v1/strategies/:uuid/briefs/:id
Polls for brief status and returns completed alignment, summary, markdown content, allocations, and checks.
/api/v1/strategies/:uuid/briefs
Lists completed briefs for a strategy, newest first.
/api/v1/strategies/:uuid/simulations
Runs an ephemeral what-if evaluation against a hypothetical portfolio without saving records.
/api/v1/strategies/:uuid/simulations/:id
Polls for a simulation result until completed or failed. Results expire after one hour.
Creating a brief is asynchronous. POST to create, then poll the show endpoint until status changes from processing to completed or error. Processing responses include polling hints. Each strategy can have one active evaluation at a time; concurrent create requests return 409 evaluation_in_progress with the active brief ID.
POST /api/v1/strategies/:uuid/briefs
-> 202 Accepted
-> { "brief": { "id": "brief-uuid", "status": "processing" } }
GET /api/v1/strategies/:uuid/briefs/:id
-> { "brief": { "status": "completed", "alignment": { "score": 0.82 } } }
JSON portfolio input must conform to the portfolio_v1 shape: stocks, options, cash, timestamp, and notes. Manual assets and liabilities live on the strategy and are included in composed portfolio reads.
{
"schema_version": "1.0.0",
"stocks": [
{ "ticker": "VOO", "shares": 50, "cost_basis": 400.00 }
],
"options": [
{ "ticker": "VOO", "type": "call", "strike": 510, "expiry": "2026-06-19", "contracts": 1, "side": "short" }
],
"cash": 8500.00,
"timestamp": "2026-02-15T12:00:00Z",
"notes": []
}
401 unauthorized
Missing or invalid API token
403 subscription_required
Active subscription required
404 not_found
Resource does not exist or is not yours
409 evaluation_in_progress
A strategy already has a running evaluation
422 invalid_params
Malformed or missing request parameters
422 validation_failed
Model validation failed
The same strategy, portfolio, brief, asset, liability, and simulation operations are available as MCP tools your agent can call directly.
See the MCP tools