Requests and models

Every request has three routing inputs.

Input	Example	Purpose
`Authorization`	`Bearer $ALIEN_AI_API_KEY`	Authenticates your Alien project
`X-Alien-External-ID`	`org_123`	Selects the customer connection
`model`	`byo/claude-opus-5`	Selects a configured model

Customer IDs

Use a stable tenant or organization ID from your own database. Resolve it after authenticating the user.

Do not let a browser choose an arbitrary X-Alien-External-ID. Anyone who can choose that value while using your server API key could target another customer’s connection.

Model IDs

Use the exact ID shown in the dashboard or returned by:

curl "https://ai.alien.dev/v1/models" \
  -H "Authorization: Bearer $ALIEN_AI_API_KEY" \
  -H "X-Alien-External-ID: $CUSTOMER_ID"

The list is specific to that customer’s connected provider and current configuration.

What model status means

Alien can report a configured model without sending a model request. The availability check does not consume model quota or accept provider terms for the customer.

configured   the customer connected a provider and the model is in its configuration
available    Alien observed the provider configuration without invoking the model
request OK   only a real completion or message request proves that request can run

Treat /v1/models as discovery, not as a synthetic inference test. Provider quota, policy, capacity, and request-specific settings can still make a real request fail.

Client protocols

Client	Endpoint
OpenAI Chat Completions	`/v1/chat/completions`
OpenAI Responses	`/v1/responses`
Anthropic Messages	`/v1/messages`

When the provider speaks the same protocol, the gateway preserves the request body. When it must translate, unsupported provider-specific or stateful fields return an error.

Open Infrastructure → Models → Provider headers to add fixed headers to every request sent to one provider. Use this for provider-required attribution or routing metadata—not per-customer secrets or values supplied by end users.

Diagnose requests

Gateway diagnostics record routing and outcome metadata, not prompt or response bodies. Search them from the CLI:

alien logs --source ai-gateway --since 24h

Useful filters include --status, --model, --provider, and --deployment-group:

alien logs --source ai-gateway \
  --status provider-error \
  --provider anthropic \
  --json

Inspect usage

alien usage ai --range 24h
alien usage ai --range 7d --json

Usage is a privacy-safe aggregate. It includes request counts, success and error totals, input and output tokens, estimated provider cost, and latency when the project’s metrics source is available.