API reference

Overview

Base URL: /api/v1 on your platform domain. Authenticate every request with a Bearer API key created in Dashboard → Security. All requests and responses are JSON. Errors return an appropriate HTTP status code and a JSON body with an “error” field.

POST /api/v1/chat/completions

Generate a model response for a conversation. The request and response shapes are OpenAI-compatible: send a “model” and an array of “messages” (each with a “role” and “content”), plus optional parameters such as “temperature”, “max_tokens” and “stream”. Usage is metered per token, and your first 20M tokens are free.

curl https://YOUR-DOMAIN/api/v1/chat/completions \
  -H "Authorization: Bearer $AI_INFRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID_FROM_GET_/api/v1/models",
    "messages": [
      { "role": "system", "content": "You are a helpful assistant." },
      { "role": "user", "content": "Summarize our launch plan in three bullets." }
    ],
    "stream": false
  }'

GET /api/v1/models

List the models currently available to your account. Use the returned “id” values in the “model” field of chat completion requests.

curl https://YOUR-DOMAIN/api/v1/models \
  -H "Authorization: Bearer $AI_INFRA_API_KEY"

POST /api/v1/revenue

Report a revenue event to VentureRails so it can be routed and invoiced. Fields: “amount_cents” (integer, required), “external_id” (string, required, your unique identifier for idempotency), “customer_email” (string, optional) and “route_id” (string, optional; defaults to your account’s default route).

curl https://YOUR-DOMAIN/api/v1/revenue \
  -H "Authorization: Bearer $AI_INFRA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount_cents": 4900,
    "external_id": "order_10293",
    "customer_email": "buyer@example.com",
    "route_id": "rt_default"
  }'

Status codes

• 200: success.
• 400: the request was malformed or missing a required field.
• 401: the API key is missing, invalid or revoked.
• 4xx with a billing error: the account has an overdue balance; settle it in the dashboard to restore access.
• 429: rate limit reached; retry with exponential backoff.
• 5xx: a temporary server issue; requests are safe to retry.

Best practices

• Keep keys on the server and rotate them regularly.
• Use a unique external_id for each revenue event so retries are idempotent.
• Stream responses for chat interfaces to improve perceived latency.
• Set per-key budgets and alerts in the dashboard.