ARTEMIS · Search

ARTEMIS base URL: https://artemis-api.trinitytrade.io

A public GET to / returns JSON with name, version, and status.

This page documents GET /health and portfolio-aware recommendation routes under /api/v1/portfolios/: Hunt (general, replacement, or interest mode) and Cash Hunt (deploy available cash). There are no separate public “demo” paths on this host—calls use the versioned paths below. Use the sections for parameters, example curls, and response sketches.

Production access. Hunt and Cash Hunt require a valid Google OIDC ID token in Authorization: Bearer when ARTEMIS runs in production. For audience values, local testing, and integration support, contact [email protected].

Authentication — Hunt and Cash Hunt

On the production host, send Authorization: Bearer <google_oidc_id_token> with a token minted for an audience configured for ARTEMIS (service-to-service integrations typically use google.oauth2.id_token.fetch_id_token with the ARTEMIS base URL as audience, consistent with other TRINITY backends). Missing or invalid tokens return 401. If OIDC audiences are not configured on the server, you may see 503. In non-production environments, ARTEMIS may not enforce this dependency—confirm with your deployment configuration.

Endpoints

GET

Health

/health

Liveness probe for load balancers and monitoring.

Auth: None — /health is public on the ARTEMIS production host.

Responses

Status Description
200 JSON: status

Example

export ARTEMIS_API="${ARTEMIS_API:-https://artemis-api.trinitytrade.io}"
curl -sS "$ARTEMIS_API/health"
GET

Hunt

/api/v1/portfolios/hunt

Portfolio opportunity analysis: general assessment (no symbol params), replacement mode (symbol_replace), or interest / suitability mode (symbol_interest). Results are paginated via page and page_size.

Auth: See Authentication — Hunt and Cash Hunt.

Parameters

Name In Type Required Description
portfolio_id query string Yes Portfolio identifier (required).
symbol_replace query string No Ticker to replace (replacement mode).
symbol_interest query string No Ticker to assess for fit (interest mode).
page query integer No 1-based page index (default 1).
page_size query integer No Rows per page (default 6, max 50).

Responses

Status Description
200 HuntResponse
400 Validation error (e.g. unknown portfolio)
401 Missing or invalid bearer token (production)
503 Authentication not configured on server
500 Server error during analysis

Example

export ARTEMIS_API="${ARTEMIS_API:-https://artemis-api.trinitytrade.io}"
export ARTEMIS_ID_TOKEN="your_google_oidc_id_token"
curl -sS -H "Authorization: Bearer $ARTEMIS_ID_TOKEN" \
  "$ARTEMIS_API/api/v1/portfolios/hunt?portfolio_id=YOUR_PORTFOLIO_ID&page=1&page_size=6"
# Optional query params: symbol_replace, symbol_interest (see description).
# Non-production servers may omit Authorization when ARTEMIS is not in production mode.
Sample JSON response 
{
  "portfolio_id": "YOUR_PORTFOLIO_ID",
  "portfolio_name": "Example",
  "hunt_mode": "general",
  "general_assessment": {
    "total_positions": 12,
    "strong_positions": 8,
    "weak_positions": 2,
    "recommendations": [],
    "concerns": []
  },
  "replacement_analysis": null,
  "suitability_analysis": null,
  "page": 1,
  "page_size": 6,
  "total_recommendations": 0,
  "has_more": false
}
GET

Cash Hunt

/api/v1/portfolios/cash-hunt

Recommendations focused on deploying available cash into new positions, respecting portfolio risk settings and pagination.

Auth: See Authentication — Hunt and Cash Hunt.

Parameters

Name In Type Required Description
portfolio_id query string Yes Portfolio identifier (required).
page query integer No 1-based page index (default 1).
page_size query integer No Rows per page (default 6, max 50).

Responses

Status Description
200 CashHuntResponse
400 Validation error
401 Missing or invalid bearer token (production)
503 Authentication not configured on server
500 Server error during cash hunt

Example

export ARTEMIS_API="${ARTEMIS_API:-https://artemis-api.trinitytrade.io}"
export ARTEMIS_ID_TOKEN="your_google_oidc_id_token"
curl -sS -H "Authorization: Bearer $ARTEMIS_ID_TOKEN" \
  "$ARTEMIS_API/api/v1/portfolios/cash-hunt?portfolio_id=YOUR_PORTFOLIO_ID&page=1&page_size=6"
# Non-production servers may omit when local auth is not enforced.
Sample JSON response 
{
  "portfolio_id": "YOUR_PORTFOLIO_ID",
  "portfolio_name": "Example",
  "available_cash": 5000.0,
  "total_capital": 100000.0,
  "recommendations": [],
  "page": 1,
  "page_size": 6,
  "total_recommendations": 0,
  "has_more": false
}