Skip to main content
Use metadata.astrolabe.stack to select a stack for one request. The value is a stack slug, such as code-agent, customer-data, or a custom stack slug from your workspace.

​
Selection precedence

Astrolabe resolves stacks in this order:
  1. metadata.astrolabe.stack
  2. API-key assignment
  3. Workspace assignment
  4. Managed default
The request override wins only for that request.

​
Supported request metadata

Astrolabe reads these fields from metadata.astrolabe:
FieldTypeEffect
stackstringSelects a stack slug for this request.
qualitystringOverrides the stack quality target. Values include draft, standard, high, and critical.
cost_modestringOverrides the stack cost mode. Values include lowest_passable, balanced, fastest_passable, premium, and fixed.
latency_slo_msnumberSets a request-level latency target in milliseconds.
verificationstringOverrides verification mode. Values include off, auto, light, strict, and strong.
fallbackbooleanEnables or disables fallback for this request.
explainbooleanRequests richer decision metadata where supported.

​
Responses example

curl https://api.astrolabe.run/v1/responses \
  -H "Authorization: Bearer $ASTROLABE_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "astrolabe/auto",
    "input": "Review this incident summary and draft an executive update.",
    "metadata": {
      "astrolabe": {
        "stack": "high-quality",
        "quality": "high",
        "cost_mode": "balanced",
        "verification": "auto",
        "fallback": true,
        "explain": true
      }
    }
  }'

​
Chat Completions example

curl https://api.astrolabe.run/v1/chat/completions \
  -H "Authorization: Bearer $ASTROLABE_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "astrolabe/coding",
    "messages": [
      {
        "role": "user",
        "content": "Find the likely cause of this TypeScript error."
      }
    ],
    "metadata": {
      "astrolabe": {
        "stack": "code-agent",
        "quality": "high",
        "verification": "strict"
      }
    }
  }'

​
Error behavior

If the stack slug is unknown, inactive, or not available to the workspace, Astrolabe returns a stack resolution error before provider execution. If the stack exists but policy boundaries reject every candidate, Astrolabe returns: 
{
  "error": {
    "code": "routing_policy_blocked",
    "message": "No allowed model candidates remain after applying routing stack boundaries."
  }
}
Use the request id and route trace to inspect rejected candidates.