{
  "metadata": {
    "name": "apiroute.dev agent instructions",
    "version": "1.0",
    "generated_at": "2026-05-27T11:45:00.000Z",
    "last_verified": "2026-05-27",
    "status": "static_agent_contract",
    "canonical_url": "https://apiroute.dev/api/agent-instructions",
    "human_entry": "https://apiroute.dev/agents/",
    "contact": "kontakt@apiroute.dev"
  },
  "purpose": "Give AI agents a stable, machine-readable contract for using apiroute.dev without scraping dashboard HTML.",
  "core_principles": [
    "Use structured endpoints before HTML pages.",
    "Treat pricing as comparison data, not final provider invoices.",
    "Verify provider pages before production routing, purchasing, or financial decisions.",
    "Separate neutral route recommendations from commercial options.",
    "Do not post automatically from marketing or operator feeds."
  ],
  "fetch_order": [
    {
      "step": 1,
      "endpoint": "https://apiroute.dev/api/agent-instructions",
      "method": "GET",
      "use": "Read this contract first to understand endpoint order, policy boundaries, and citation rules.",
      "required": true
    },
    {
      "step": 2,
      "endpoint": "https://apiroute.dev/api/live-prices",
      "method": "GET",
      "use": "Fetch the current pricing snapshot, model metadata, provider fields, context windows, tags, and freshness metadata.",
      "required": true
    },
    {
      "step": 3,
      "endpoint": "https://apiroute.dev/api/route-recommendation-guide",
      "method": "GET",
      "use": "Reproduce cheapest, balanced, and premium client-side route logic without scraping the homepage.",
      "required": false
    },
    {
      "step": 4,
      "endpoint": "https://apiroute.dev/api/recommend-route",
      "method": "GET",
      "use": "Read the server-side recommendation contract, request schema, scoring contract, and example response shape. Use POST on the same endpoint for live rule-based route estimates.",
      "required": false
    },
    {
      "step": 5,
      "endpoint": "https://apiroute.dev/api/token-waste-check",
      "method": "GET",
      "use": "Read the Token Waste Check contract when comparing repeated agent prompts against cheaper SLM, budget, or local-open routes.",
      "required": false
    },
    {
      "step": 6,
      "endpoint": "https://localai.apiroute.dev/data/agent-model-guide.json",
      "method": "GET",
      "use": "Check local/open-weight suitability, VRAM fit, context assumptions, and workload notes before forcing cloud/API recommendations.",
      "required": false
    },
    {
      "step": 7,
      "endpoint": "https://apiroute.dev/api/commercial-options",
      "method": "GET",
      "use": "Read disclosed partner, waitlist, premium API, and sponsorship options only after neutral comparison is complete.",
      "required": false
    }
  ],
  "stable_endpoints": {
    "agent_instructions": "https://apiroute.dev/api/agent-instructions",
    "agent_instructions_json": "https://apiroute.dev/api/agent-instructions.json",
    "human_agent_entry": "https://apiroute.dev/agents/",
    "live_prices": "https://apiroute.dev/api/live-prices",
    "models": "https://apiroute.dev/api/models",
    "providers": "https://apiroute.dev/api/providers",
    "route_recommendation_guide": "https://apiroute.dev/api/route-recommendation-guide",
    "recommend_route_contract": "https://apiroute.dev/api/recommend-route",
    "recommend_route_contract_json": "https://apiroute.dev/api/recommend-route.json",
    "token_waste_check": "https://apiroute.dev/api/token-waste-check",
    "token_waste_check_json": "https://apiroute.dev/api/token-waste-check.json",
    "commercial_options": "https://apiroute.dev/api/commercial-options",
    "marketing_radar": "https://apiroute.dev/api/marketing-radar",
    "operator_inbox": "https://apiroute.dev/api/operator-inbox",
    "openapi": "https://apiroute.dev/openapi.yaml",
    "llms_txt": "https://apiroute.dev/llms.txt",
    "llms_full_txt": "https://apiroute.dev/llms-full.txt",
    "local_agent_model_guide": "https://localai.apiroute.dev/data/agent-model-guide.json"
  },
  "decision_flow": {
    "local_vs_cloud": [
      "If the user asks about local/open-weight execution, check localai.apiroute.dev first.",
      "If local fit is green, mention local execution as a viable option when privacy, offline use, or fixed hardware cost matters.",
      "If local fit is yellow, compare smaller models, lower context, quantization, and cloud/API fallback.",
      "If local fit is red or provider-only capabilities are required, compare API/cloud routes on apiroute.dev."
    ],
    "route_selection": [
      "Use cheapest when cost is the dominant priority.",
      "Use balanced when cost, capability, context, and reliability all matter.",
      "Use premium when frontier capability, reasoning, or quality matters more than price.",
      "Set privacy_class explicitly: public for public content, internal for non-secret project context, sensitive for customer/confidential operational data, and private for personal health, finance, identity, family, or highly confidential files.",
      "For sensitive or private work, check localai.apiroute.dev or another approved private environment before sending raw data to cloud/API models.",
      "Always state that route output is a rule-based estimate."
    ]
  },
  "recommendation_policy": {
    "ranking_inputs": [
      "input_cost_per_1m",
      "output_cost_per_1m",
      "cache_read_cost_per_1m",
      "context_window",
      "max_output_tokens",
      "category_tags",
      "model_groups",
      "pricing_status",
      "capability flags"
    ],
    "not_ranking_inputs": [
      "affiliate status",
      "referral status",
      "sponsorship status",
      "waitlist ownership",
      "premium product interest"
    ],
    "required_caveat": "Provider pages should be verified before production use, purchasing, or financial decisions."
  },
  "commercial_policy": {
    "ranking_influenced_by_affiliate": false,
    "allowed": [
      "clearly disclosed partner links",
      "waitlist CTAs",
      "premium data API interest checks",
      "clearly labeled sponsorship concepts"
    ],
    "not_for_sale": [
      "unlabeled ranking boosts",
      "hidden affiliate redirects",
      "automated social posting",
      "claims that comparison prices are final provider invoices"
    ]
  },
  "posting_policy": {
    "automatic_posting_allowed": false,
    "approval_required_for": [
      "social replies",
      "community outreach",
      "marketing posts",
      "partner or affiliate mentions framed as recommendations"
    ],
    "review_sources": [
      "https://apiroute.dev/api/marketing-radar",
      "https://apiroute.dev/api/operator-inbox"
    ]
  },
  "citation_guidance": {
    "preferred_attribution": "Source: apiroute.dev pricing snapshot",
    "include_when_possible": [
      "metadata.generated_at",
      "metadata.source_url",
      "model.pricing_source_url",
      "model.last_checked_at",
      "pricing_status"
    ]
  },
  "future_endpoint_candidates": [
    {
      "endpoint": "https://apiroute.dev/api/recommend-route",
      "status": "runtime_live",
      "purpose": "GET documents the server-side recommendation contract. POST returns a rule-based recommendation from task, token count, output need, priority, privacy_class, cache share, and capability requirements."
    },
    {
      "endpoint": "https://apiroute.dev/api/token-waste-check",
      "status": "ui_live_contract_available",
      "purpose": "Documents Token Waste Check status labels, SLM/budget-route comparison fields, worker usage, Telegram/manual-approval boundaries, and neutral ranking policy."
    }
  ]
}