com.argosvix/server

Mark an individual alert firing (event) as handled / acknowledged. Unlike silence_alert (which temporarily mutes the whole alert rule), ack is a per-event receipt — future firings of the same rule are still delivered as usual. Pass the id obtained from list_alert_events as eventId. Re-acking an already acknowledged event does not overwrite the existing ack info (the first acknowledgedAt / acknowledgedBy) and returns 200 (idempotent; distinguishable via the alreadyAcknowledged flag).

Get an aggregation cube over calls (POST /v1/query/aggregate). groupBy (provider / model / day / hour / minute / tag / error) x metric (cost / latency / tokens / input_tokens / output_tokens / cached_tokens / cache_savings / count / error_rate) — e.g. "aggregate this month's cost by model" in one call. tag mode requires tagKey (alphanumerics plus _ - only, e.g. 'env' / 'feature'). error mode aggregates only error rows by error string (which errors, how many; metric=count recommended). hour mode caps at 168h / minute mode at 60min (400 beyond). cost = SUM(cost_usd) / latency = AVG(latency_ms) / tokens = SUM(total_tokens) / input_tokens = SUM(prompt_tokens) / output_tokens = SUM(completion_tokens) / cached_tokens = SUM(cached_read_tokens) / cache_savings = SUM(cache_savings_usd) / count = COUNT(*) / error_rate = errors / total. Returns { groups: [{key, value, count}], total: {value, count} }.

Apply a user-facing promotion code already registered in Stripe (e.g. 'LAUNCH50') to your account's Stripe subscription (POST /v1/tier2/promo/apply). Internal operations tool (support use); customer accounts receive 403. It will not be opened up without terms covering economically impactful operations (timing undecided). 409 if an active discount already exists (structural defense against stacking), and 409 when the status is canceled / incomplete_expired. Redemption is delegated to Stripe via promotion_code (applying coupons directly is forbidden as a constraint bypass); dryRun must be passed explicitly, and idempotencyKey is required when dryRun=false. Re-calls with the same key return the cached result via the tier2_idempotency table, structurally serializing concurrent applies. dryRun=true previews resolution + the active-discount check + the estimated discount only (no Stripe mutation); dryRun=false applies the promotion code.

Bulk-silence noisy alerts that fired repeatedly in the past hour (POST /v1/tier2/alerts/auto-silence). Finishes "this alert fired 50 times in the past hour — silence it for an hour" in one prompt. Specify exactly one of alertId (silence a single alert) or byVolumeThreshold (all alerts with N+ firings in the past hour). silenceDurationMinutes is 5-1440 (5 minutes to 24 hours), default 60. An optional reason can be attached. dryRun=true previews the targets with fireCount; dryRun=false UPDATEs alerts.silenced_until and emits an audit event per alert (tier2.auto_silence_noisy_alert). Because this is a reversible mutation (the existing unsilence_alert can undo it) with strict per-account scoping (other accounts' alerts are unaffected), no special authorization is required — Pro+ accounts can call it directly. Returns (dryRun=true) { dryRun: true, targetCount, silenceUntil, silenceDurationMinutes, lookbackStart, targets: [{alertId, name, fireCount}] }; (dryRun=false) { dryRun: false, targetCount, silenceUntil, silenceDurationMinutes, succeeded: string[], failed: [{alertId, reason}], skipped: string[], reason }. idempotencyId = sha1(endpoint+accountId+alertId+silenceUntil truncated to the minute), coalescing duplicate runs within the same minute.

Bulk-delete the given call ids (max 100), scoped to your account (POST /v1/calls/bulk-delete). Useful for cleaning up junk calls accumulated during development and testing. dryRun=true returns the matched count before deleting. The delete is one atomic SQL statement; a bulk_deleted event is recorded in the audit log. Per FK constraints, related traces / annotations / scores are cascade-deleted via ON DELETE.

Batch safety-classify unclassified calls on demand (via OpenAI Moderation, POST /v1/safety-assessments/scan-batch). Complements the cron (every 15 min, 50 records) with a "right now" path — an AI agent can finish "classify all of last week's calls" in one prompt. Pro+ only (Free relies on the cron); the backend enforces the plan gate and budget gate. maxRecords (1-100, default 50); returns { scanned, assessed, flagged, failures, skipped }. Recorded with source='mcp' (distinguished from cron entries, so the dashboard can visualize on-demand classification). Audit: emits a safety.scan_batch_run event to the audit log.

Compare two eval runs (baseline / candidate) and return per-criterion mean score deltas + the failed count delta + a verdict (GET /v1/eval-runs/compare). Lets an AI agent grasp "how did the candidate change relative to the baseline" in one call, for prompt-improvement measurement and regression detection. verdict = improved / regressed / mixed / unchanged. The failed count treats scores <= 2 as "failed". Same account only.

Create a new alert rule. Watches for cost / error rate / latency / anomaly threshold breaches and notifies the specified channels. Example: "notify me by email when daily cost exceeds $10". channelKinds is an array of channel kinds to enable; channelTargets is an object keyed by those kinds holding the destinations (e.g. channelKinds:["email"], channelTargets:{"email":"dev@example.com"}). Every kind listed in channelKinds must have a destination in channelTargets. anomaly_* types interpret thresholdValue as a standard-deviation multiplier (0.5-10, e.g. 3 = 3 sigma). The Free plan allows the email channel only and up to 3 alerts (the backend returns 403 beyond that).

Create a new annotation (human review / labeling) for an LLM call. Specify at least one of annotationText / label / qualityScore (an "empty annotation" gets 400 from the backend). Example phrasing: "Claude, label this call 'badly-summarized' with quality 2", or bulk-apply positive / negative labels for an eval loop. Combined with the eval baseline runner (run_eval), annotations can calibrate eval criteria as ground truth.

Create a runtime budget gate (Pro+ only). Sets a monthly LLM spend limit (USD) for the account; the SDK (budgetGate opt-in) blocks over-limit calls before execution. Enforcement is optimistic (spend is cached for 60 seconds and in-flight calls pass, so the limit is a guideline that can be exceeded, not a strict hard cap). enforceMode = fail_open (default; calls pass when the backend is unreachable) / fail_closed (calls are blocked when unreachable; a cold start where the SDK has never fetched the config additionally requires the SDK-side failClosed opt-in). Omitting projectId = an account-wide gate (only one; 409 if one exists). Specifying projectId = a gate for that project only (ANDed with the account gate — the strictest limit wins; one per project). Specifying tagKey + tagValue = a gate for calls carrying that tag (e.g. tagKey=service / tagValue=checkout caps the monthly spend of service=checkout. ANDed with the account gate; one per (tagKey,tagValue)). tagKey/tagValue must be specified together and are mutually exclusive with projectId. Example phrasing: "create a budget gate at $50/month" / "cap project X at $10/month" / "cap the service=checkout tag at $20/month"

Create one custom eval criterion in your account (Pro+ only). name + rubric + scaleMin + scaleMax are required. Same name already existing in the account = 409. A name matching a global default is structurally allowed (UNIQUE (account_id, name) separates it from account_id IS NULL). type defaults to 'llm_judge' (judge LLM scoring). Specifying a deterministic evaluator type (exact_match / contains / regex / json_schema / json_path) scores without calling an LLM — free and instant (pass -> scaleMax / fail -> scaleMin). Deterministic types require config. The path an AI agent takes when it decides "add this criterion" while evaluating your own workloads.

Create a golden dataset (POST /v1/eval-datasets, Pro+ only). items can carry up to 20 test cases with expected outputs. Up to 50 datasets per account. frozen=true freezes the population (items can no longer be changed or unfrozen — fixing comparability for regression verdicts).

Create a runtime policy gate (Pro+ only). Configures an account-wide model allowlist / PII block / secret block; the SDK (policyGate opt-in) blocks violating calls before execution. At least one rule (modelAllowlist / blockPii / blockSecrets) is required. One per account (409 if one exists). A redact mode is not supported (block only). Example phrasing: "only allow gpt-5.5 and claude-fable-5" / "block calls containing PII"

Create a new project (POST /v1/projects). name = display name; slug = a short URL-safe identifier (/^[a-z][a-z0-9-]{0,31}$/). Pro caps at 5 projects, Team unlimited, Free cannot create (403). As a mutation, session-authenticated requests enforce Origin/Referer (dashboard-driven).

Register one new prompt template (Pro+ only). name + version + template are required; variables / labels / description are optional. An existing (name, version) pair returns 409 (UNIQUE constraint). Used when an AI agent auto-registers templates for evals / experiments.

Create a new saved view, or overwrite when the name exists (POST /v1/saved-views). name is unique within the account. filter follows the SavedViewFilter shape (startDate / endDate / provider / model / limit / preset / sortBy? / sortOrder?). Lets an AI agent save frequently used filters under a name — e.g. create a "last 7 days, GPT-4 only" view and recall it later.

Register one outbound event webhook (Pro+ only, POST /v1/webhooks). url (HTTPS required; SSRF defense rejects private/loopback) + optional secret (HMAC-SHA256 signing key) + eventTypes (array of event kinds to subscribe to; omitted / empty = subscribe to everything). Up to 10 per account. Delivery payload = { event, eventId, occurredAt, accountId, data }; with a secret set, an X-Argosvix-Signature header is attached.

Delete an alert (DELETE /v1/alerts/:id). Related alert_events are CASCADE-deleted too. To guard against accidental deletion, checking the details with get_alert first is recommended. If you only want to pause an alert, prefer silence_alert (mute) or update_alert with enabled=false instead of delete (both are recoverable).

Delete an annotation (DELETE /v1/annotations/:id). No other rows depend on it, so there is no CASCADE impact. To guard against accidental deletion, checking the details with get_annotation first is recommended.

Delete a runtime budget gate (Pro+ only). After deletion the SDK's pre-execution enforcement is disabled. To pause temporarily, prefer update_budget_gate with enabled: false.

Delete a custom criterion in your account (Pro+ only, DELETE /v1/eval-criteria/:id, 204). Global defaults (account_id IS NULL) are structurally out of scope = 404; other accounts are 404 too. WARNING: all past eval_run score rows for this criterion (eval_scores) are physically deleted at the same time via ON DELETE CASCADE — historical comparisons and score trend analysis become permanently impossible. This is not a tool for an AI agent to call casually while tidying up criteria; only proceed when the user has explicitly confirmed the past run scores are not needed. If you only want to rename, using update_eval_criterion (full replace) with name + rubric + scaleMin + scaleMax preserves the history.

Delete a golden dataset (DELETE /v1/eval-datasets/:id, Pro+ only). Items are cascade-deleted. Past eval runs / scores remain.

Delete a runtime policy gate (Pro+ only). To pause temporarily, prefer update_policy_gate with enabled: false.

Soft-delete a project (DELETE /v1/projects/:id; sets archived_at for a logical delete). The default project cannot be deleted (400, keeping accounts.default_project_id referentially consistent). After archiving, calls / alerts remain as-is (past observations are kept); route new records to another project.

Delete an existing prompt (Pro+ only, DELETE /v1/prompts/:id, 204 No Content). Scoped to your account (other accounts' ids return 404). WARNING: physical delete with no restore; past eval_runs' prompt_registry_id is SET NULL, losing the trace of which prompt template each run used (history comparisons can no longer be linked). Even when sunsetting an old version in a rotation, while past run traces remain it is safer to do a logical sunset via update_prompt with labels such as 'sunset'.

Delete the saved view with the given id (DELETE /v1/saved-views/:id). Scoped to your account.

Delete an outbound event webhook (Pro+ only, DELETE /v1/webhooks/:id). Other accounts' webhooks return 404. webhookId is the id from list_webhooks.

Deploy a specific prompt version to a label (an environment such as production / staging) (Pro+ only, POST /v1/prompts/:id/deploy). If a deployment already exists, the prior version is kept as previous and rollback_prompt can revert in one step. Re-deploying the same version does not create a previous entry. Labels are per prompt name (each name has its own production version).

Compare the current window against a baseline window (the immediately preceding window of the same length) and detect anomalies across 4 axes: cost / latency / error_rate / call_volume — lets an AI grasp "is anything off?" in one prompt. Sensitivity is tunable via threshold: sensitive (1.5x) / normal (2x, default) / conservative (3x). 0-4 detections, each with a narrative. Returns { window, threshold, multiplier (the numeric factor behind threshold), current: {...}, baseline: {...}, anomalies: [{ axis, severity: 'minor'|'major'|'critical', current, baseline, ratio, narrative }], partialFailures?: string[] (axes that failed to fetch, as 'current:xxx' / 'baseline:xxx'; omitted when everything succeeds) }. errorRate is evaluated and displayed as a percent (0-100), matching the backend aggregate unit. Insufficient baseline data (fewer than 10 records in the period) yields anomalies: [] plus a warning message (this path omits multiplier; partialFailures is optional in the same way).

Large-batch export of calls (POST /v1/query/export). Higher limit than query_calls (per-plan max records: Free 1000 / Pro 50000); available on all plans. Filter axes = startTime / endTime / provider / model plus limit. Example phrasing: "pull all of last month's GPT-4 calls and analyze the trends" — one call. The result format is the same JSON as query_calls (the AI can feed it straight into CSV / statistics).

Extend your account's Stripe subscription trial by 1-30 days (POST /v1/tier2/trial/extend). Internal operations tool (support use); customer accounts receive 403. Trial extension directly affects revenue, so there is no plan to open it up. Cumulative cap of 60 days (aggregated from the last 30 days of audit logs); 409 unless status='trialing'. dryRun must be passed explicitly (guards against accidental mutation via an implicit false); when dryRun=false, idempotencyKey is also required (16-128 alphanumeric plus '_-'). Re-calling with the same key returns the cached result via the tier2_idempotency table (structurally preventing retry double-extends). dryRun=true previews previousTrialEnd / newTrialEnd / the cumulative total only (no Stripe call); dryRun=false performs the actual Stripe mutation plus the accounts_subscription sync update.

Get a health summary of your LLM infrastructure in one call. Fetches 4 existing endpoints in parallel (aggregate_calls / get_percentiles / get_llm_budget / list_audit_log) and compresses them into one response. Returns { window, totals: {calls, costUsd, errorRate (percent 0-100)}, latency: {p50, p95, p99 (ms)}, budget: {used, limit, percentUsed (0-100)}, recentEvents: count, summary: 'ok' | 'warn' | 'critical', partialFailures?: string[] (axes that failed to fetch; omitted when everything succeeds) }. critical = errorRate>=10% / budget>=90% / p95>=10s; warn = >=3% / >=70% / >=3s. Example phrasing: "how is our LLM infra doing right now?" — answered in one prompt. Pure read aggregator (no new backend endpoint); individual endpoint failures return partial results (one axis timing out does not block the summary; failed axes are listed in partialFailures).

Return the detailed configuration of an alert and its recent trigger history. Pass the alertId obtained from list_alerts. Use it to check the threshold / notification channels / silence state / when it fired.

Fetch one annotation by id (obtained from list_annotations_*). Includes annotationText / label / qualityScore / callId / createdAt / updatedAt / createdByUserId. Ids belonging to other accounts return 404 (structural defense).

Get the current state of an approval request. status = pending / approved / denied / expired. Do not perform the target operation unless the status is approved (default-deny). Dangerous mutation tools also support server-side consumption via their approvalId param (see the request_approval description).

Get the runtime budget gate settings (part of the runtime control plane) plus this month's LLM spend. Response = { gates: [{ id, projectId, monthlyLimitUsd, enforceMode, enabled, ... }], spentUsdThisMonth, monthStart, ttlSeconds }. monthStart is the UTC month start. The same source the SDK's budgetGate opt-in evaluates before execution. Distinct from get_llm_budget (which caps Argosvix's internal AI feature costs) — this one is a monthly cap on your own LLM spend. Example phrasing: "how much budget gate headroom is left this month?" / "is the gate set to fail_open?"

Return cost / call count / token aggregates per time range, with a per-provider breakdown. When groupBy="none" is specified, a per-provider breakdown is still returned for backend compatibility (check the response.total field for the overall sum).

Fetch a Readthrough issue (Argosvix's agent reads one trending OSS repo per day via the GitHub API and records what it found). Public data tool — works without an API key. Omit date = latest issue; date (YYYY-MM-DD) = that issue. Response = { issue: { date, repo: { owner, name, url, language?, license?, stars? }, oneLiner, oneLinerEn?, keyFiles: [{ path, why, whyEn? }], highlights, cautions, generation?, traceId?, generatedAt } }. A reading guide, not a review — "files worth reading", "design highlights", "facts to check before adopting". Use for: "what's today's featured OSS repo?" "what should I check before adopting this repo?"

Resolve and return the prompt version currently deployed to the given environment (name + label) (GET /v1/prompts/resolve, available on Free). The main runtime path for an agent to fetch the "production prompt". Returns that version's template / variables / labels / version. 404 when nothing is deployed.

Fetch one criterion's detail (name / rubric / scaleMin / scaleMax / createdAt) by id. The id comes from list_eval_criteria.criteria[].id. Both global defaults (accountId NULL) and your account's custom criteria are accepted; other accounts' customs return 404 (structural defense).

Fetch one dataset's detail plus all of its items (GET /v1/eval-datasets/:id). datasetId is list_eval_datasets.datasets[].id.

Fetch one eval run's detail plus the list of per-(criterion x call) scores. Use runs[].id from list_eval_runs as-is. The scores array includes score (an integer within the criterion's scale) + reasoning (the judge's rationale). Same endpoint as the argosvix://eval-runs/{id} resource template.

Get the current monthly LLM feature budget (the LLM cost cap covering the 3 axes: safety classifier + secondary PII audit + eval baseline runner). Response = { budgetUsd, spentUsd, remainingUsd, periodStart, defaultBudgetUsd, minBudgetUsd, maxBudgetUsd }. Readable on Free and Pro+ alike; used when an AI agent decides "have we hit 80% of budget?" / "should we raise it?". Default $5/month; auto-resets at month boundaries (per YYYY-MM).

Get percentile metrics over calls (POST /v1/query/percentiles). metric = 'latency' (ms) or 'cost' (USD); either a single value for the whole range, or a time series with groupBy='day'/'hour'/'minute'. Example phrasing: "daily p95 latency trend for last week". Percentiles are computed with the nearest-rank method.

Get the runtime policy gate settings (part of the runtime control plane). Response = { policy: { id, modelAllowlist, blockPii, blockSecrets, enforceMode, enabled, ... } | null }. The config the SDK's policyGate opt-in evaluates locally before each LLM call (exact-match model allowlist + blocking on PII / secret detection). Example phrasing: "what model restrictions are active right now?" / "is PII blocking enabled?"

Fetch one prompt's detail by id. Use prompts[].id from list_prompts as-is. Includes template + variables + labels + description; scoped to your account (structurally enforced by a backend WHERE clause — other accounts' ids return 404). Same endpoint as the argosvix://prompts/{id} resource template.

Return the thread for a proposal (the questions asked so far and the AI's replies). Get proposalId from list_proposals.

Fetch one assessment's detail by id. Use assessments[].id from list_safety_assessments as-is. Includes labels (array of flagged categories) + score (max category score 0-1) + reasoning + classifier_id + source. Same endpoint as the argosvix://safety-assessments/{id} resource template.

Fetch Synth Daily issue data (a daily AI digest produced by Argosvix's own agent pipeline). Public data tool — works without an API key (alongside get_daily_readthrough). Omit date = latest issue; date (YYYY-MM-DD) = that issue. Response = { issue: { date, scoop, items: [{ rank, name, desc, why, sourceUrl, metric, nameEn?, descEn?, whyEn? }], generatedAt } }. desc/why are Japanese, descEn/whyEn are English. metric carries first-party numbers (e.g. '+4,349 stars/day'). Use for: "what's new in AI today?" "any new models or price cuts?"

Return alert trigger events, newest first. Account-wide (recent firings of all alerts) by default; pass alertId to narrow to one alert. Use for questions like "which alerts fired recently and how often?" or "when did the cost alert go off?". Each event's id can be passed directly to the acknowledge_alert tool. acknowledgedAt / acknowledgedBy are null if not yet acknowledged. Each event includes a snapshot of thresholdValue / windowMinutes / alertType at firing time (so the firing-time conditions survive later rule edits). For the next page, pass the last event's triggeredAt + id as beforeTriggeredAt + beforeId (keyset cursor).