Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content
Start Here

Getting Started

Minima is a hosted API. There is nothing to install or run — you call the service with an API key, get a model recommendation, run that model in your own stack, and report the outcome so the next pick gets sharper — or run your own instance instead: see Self-hosting. This walks you from a key to a closed feedback loop.

Prerequisites

  • A Mubit API key (mbt_…) — your Mubit data-plane key. Minima passes it through on each request to read and write your task → model → outcome history in Mubit; there is no separate Minima key. Request access if you don't have one yet.
  • Nothing else. Minima computes its own embeddings server-side — there's no model, database, or runtime for you to operate.
ℹ️Note

Base URL. All requests go to https://api.minima.sh. The examples below read your Mubit key from a MUBIT_API_KEY environment variable — export MUBIT_API_KEY=mbt_… before running them.

  1. Make your first recommendation
    curl -s https://api.minima.sh/v1/recommend \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
        "task": {"task": "Summarize this 2-page incident report into 3 bullet points.",
                 "task_type": "summarization"},
        "cost_quality_tradeoff": 3
      }' | jq

    You get back a recommendation_id, a recommended_model, a ranked candidate list, a fallback_model, and a decision_basis (memory | prior | llm).

  2. Run the model yourself

    Minima hands back the pick — it never proxies, executes, or rewrites. Run the recommended model in your own stack with your own provider credentials. Keep the recommendation_id; you'll quote it back in the next step.

  3. Close the loop

    Tell Minima how it went. This is what makes the next recommendation sharper — and it populates the realized cost/token history that powers accurate cost ranking. evidence_source declares where the label came from (gate for a deterministic check, judge for an LLM judge, human for your own assertion, none for unlabeled telemetry).

    curl -s https://api.minima.sh/v1/feedback \
  -H "authorization: Bearer $MUBIT_API_KEY" \
  -H 'content-type: application/json' \
  -d '{
        "recommendation_id": "<from step 1>",
        "chosen_model_id": "claude-haiku-4-5",
        "outcome": "success",
        "quality_score": 0.95,
        "input_tokens": 1180,
        "output_tokens": 320,
        "actual_cost_usd": 0.0028,
        "evidence_source": "human"
      }' | jq
💡Tip

Cold start. On day one your account has little history, so early picks lean on capability priors (decision_basis: "prior", a cold_start warning) and the cheap-LLM reasoner fires more often. As your /v1/feedback outcomes accumulate, recommendations shift to decision_basis: "memory" and the cost ranking sharpens automatically — see How it gets better over time.

Next steps

  • Use the typed Python Client SDK instead of raw curl.
  • Read Concepts to understand the slider, the cost-basis tiers, and the escalation path.
  • Browse the Examples for constraints, workflows, and a production routing wrapper.
  • Prefer the terminal? The Minima CLI wraps this whole loop in a coding agent.