How do I authenticate to the VerticalAPI?

Pass your VerticalAPI access key in the Authorization header as 'Bearer vapi_your_key_here'. Your LLM provider key is sent separately via the X-Provider-Key header. Beta access is issued directly by VerticalAPI.

Is the API OpenAI-compatible?

The /v1/chat/completions endpoint is designed around the OpenAI Chat Completions request and response shape. Use https://api.verticalapi.com/v1 as the base URL and verify the features your application relies on during the beta.

What model names should I pass?

Pass a vertical slug as the model field — for example 'code-reviewer', 'copywriter', 'financial-analyst' or 'geopolitical-risk'. The current list available to an access key is returned by GET /v1/models.

How do streaming responses work?

Set 'stream': true in the request body to receive Server-Sent Events. Each chunk is a data line containing a delta object and the stream terminates with data: [DONE]. Verify the event shape with the SDK version used by your beta client.

Gateway beta documentation

Product boundary: The public model and provider intelligence directory is VerticalAPI's primary product. This page documents a secondary BYOK gateway utility in beta. Test compatibility and limits against your workload before relying on it.

The gateway exposes an OpenAI-compatible /v1/chat/completions endpoint at https://api.verticalapi.com/v1. Authenticate with a VerticalAPI Bearer token, set model to a vertical slug and pass the upstream LLM provider key via X-Provider-Key.

Quickstart

Use an OpenAI SDK or a direct HTTP request. The endpoint follows the OpenAI Chat Completions shape; beta clients should verify each required option.

Base URL: https://api.verticalapi.com/v1

Python (OpenAI SDK)

quickstart.pypython

from openai import OpenAI

client = OpenAI(
    base_url="https://api.verticalapi.com/v1",
    api_key="vapi_your_key_here",
    default_headers={"X-Provider-Key": "your_provider_key"},
)

response = client.chat.completions.create(
    model="geopolitical-risk",
    messages=[{"role": "user", "content": "Analyze Iran-Israel escalation dynamics"}],
)

print(response.choices[0].message.content)

cURL

terminalbash

curl -X POST https://api.verticalapi.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer vapi_your_key_here" \
  -H "X-Provider-Key: your_provider_key" \
  -d '{
    "model": "geopolitical-risk",
    "messages": [{"role": "user", "content": "Risk level for Strait of Hormuz?"}],
    "stream": false
  }'

Streaming

streaming.pypython

stream = client.chat.completions.create(
    model="geopolitical-risk",
    messages=[{"role": "user", "content": "Analyze Iran-Israel escalation"}],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

Authentication

All API requests require a vapi_ API key passed via the Authorization header.

headerhttp

Authorization: Bearer vapi_your_key_here

VerticalAPI access keys are hashed server-side. Upstream provider credentials can be sent per request through X-Provider-Key.

Beta access is issued directly. Contact VerticalAPI with the provider and workload you want to test.

Chat Completions

POST /v1/chat/completions

Create a chat completion using a vertical model. The request and response are designed around the OpenAI Chat Completions shape.

Request body

Parameter	Type	Required	Description
model	string	Yes	Vertical slug (e.g. `"geopolitical-risk"`)
messages	array	Yes	Array of message objects with `role` and `content`
stream	boolean	No	Enable SSE streaming (default: false)
temperature	float	No	Sampling temperature (0.0 - 1.0)
max_tokens	integer	No	Maximum output tokens (default: 4096, max: 8192)
tools	array	No	Additional tool definitions (merged with vertical's built-in tools)
tool_choice	string	No	Tool selection mode

Response

response.jsonjson

{
  "id": "chatcmpl-vapi-abc123",
  "object": "chat.completion",
  "created": 1234567890,
  "model": "geopolitical-risk",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Based on current intelligence signals..."
    },
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 1847,
    "completion_tokens": 256,
    "total_tokens": 2103
  }
}

Note: The model field in the response always returns the vertical slug, not the backend model. This is by design — the backend model is an implementation detail.

Streaming

Set "stream": true to receive Server-Sent Events (SSE) in OpenAI format:

SSE streamtext

data: {"id":"chatcmpl-vapi-abc123","choices":[{"delta":{"role":"assistant"},"finish_reason":null}]}

data: {"id":"chatcmpl-vapi-abc123","choices":[{"delta":{"content":"Based on"},"finish_reason":null}]}

data: {"id":"chatcmpl-vapi-abc123","choices":[{"delta":{"content":" current"},"finish_reason":null}]}

data: {"id":"chatcmpl-vapi-abc123","choices":[{"delta":{},"finish_reason":"stop"}]}

data: [DONE]

List Models

GET /v1/models

Returns available verticals in OpenAI models list format.

responsejson

{
  "object": "list",
  "data": [
    {
      "id": "geopolitical-risk",
      "object": "model",
      "owned_by": "verticalapi",
      "description": "AI model specialized in geopolitical risk analysis"
    }
  ]
}

Health Check

GET /health

responsejson

{"status": "ok", "version": "0.1.0"}

Errors

VerticalAPI returns OpenAI-compatible error responses:

Status	Type	Description
401	authentication_error	Missing or invalid API key
404	not_found_error	Unknown vertical/model slug
429	rate_limit_error	Rate limit exceeded (check `Retry-After` header)
400	invalid_request_error	Malformed request body
502	api_error	Backend provider error

error responsejson

{
  "error": {
    "message": "Model 'xxx' not found. Available: geopolitical-risk",
    "type": "not_found_error",
    "code": "model_not_found"
  }
}

Verticals

Each vertical is a pre-configured AI model with a built-in system prompt, tool definitions, and intelligent model routing.

geopolitical-risk

Senior geopolitical risk analyst with expertise in conflict dynamics, economic warfare, and strategic intelligence.

System prompt: 2000-token expert analyst persona
Tools: get_crisis_index, search_conflict_events, get_sanctions_status, get_country_risk_profile, analyze_escalation_ladder, get_commodity_impact
Routing: Sonnet default, Opus for complex analysis ("scenario analysis", "wargame", "deep analysis"), Haiku for free tier and short queries

Current catalogue: Use GET /v1/models for the verticals available to your key. Do not rely on a static marketing list for beta availability.

SDK Support

VerticalAPI is designed for OpenAI SDK compatibility. Change base_url, use the VerticalAPI key as api_key, pass the provider credential as a default header and test the options your application requires.

Python

python

from openai import OpenAI
client = OpenAI(
    base_url="https://api.verticalapi.com/v1",
    api_key="vapi_...",
    default_headers={"X-Provider-Key": "your_provider_key"},
)

JavaScript / TypeScript

javascript

import OpenAI from 'openai';
const client = new OpenAI({
  baseURL: 'https://api.verticalapi.com/v1',
  apiKey: 'vapi_...',
  defaultHeaders: { 'X-Provider-Key': 'your_provider_key' },
});

Go

client := openai.NewClient(
    option.WithBaseURL("https://api.verticalapi.com/v1"),
    option.WithAPIKey("vapi_..."),
)

cURL

bash

curl https://api.verticalapi.com/v1/chat/completions \
  -H "Authorization: Bearer vapi_..." \
  -H "X-Provider-Key: your_provider_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"geopolitical-risk","messages":[...]}'

Access & Rate Limits

The gateway is a secondary beta utility and does not currently publish self-serve subscription tiers on this page. Access and limits are confirmed directly for the workload being tested. The public model directory and comparisons remain free to read.

Rate limit headers are included in every response:

X-RateLimit-Limit — requests per minute for your access allocation
X-RateLimit-Remaining — remaining requests in current window
X-RateLimit-Reset — seconds until window resets
Retry-After — seconds to wait (only on 429 responses)

Changelog

v0.1.0 — April 2026

Initial release
OpenAI-compatible proxy with streaming support
First vertical: Geopolitical Risk Analyst
API key authentication and rate limiting
Intelligent model routing (Haiku / Sonnet / Opus)