Start

Quickstart

Your first call takes a base URL, a virtual key and an alias. Every example below uses placeholders: replace them with the values from your invitation.

Early accessBy invitationLast updated 5 October 2026

Before you start

An invitation gives you three things:

A base URL It ends in /v1. We do not publish it; it comes with the invitation.
A virtual key One per app, sent to you privately. It is not a provider key and works only on this gateway.
Your model list The aliases your key may call, chosen from the data class of what your app sends.

No invitation yet? See how access works.

Set two variables

bash

export ASKSHIVA_BASE_URL="https://YOUR-GATEWAY-HOST/v1"   # from your invitation
export ASKSHIVA_API_KEY="YOUR_VIRTUAL_KEY"                # keep it server-side

PowerShell

powershell

$env:ASKSHIVA_BASE_URL = "https://YOUR-GATEWAY-HOST/v1"   # from your invitation
$env:ASKSHIVA_API_KEY  = "YOUR_VIRTUAL_KEY"                # keep it server-side

First request

A normal OpenAI-style chat request. Only the base URL, the key and the model name are AskShiva-specific.

curl

bash

curl "$ASKSHIVA_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ASKSHIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "askshiva-smart",
    "messages": [
      {"role": "system", "content": "Answer in two sentences."},
      {"role": "user", "content": "What does an AI gateway do?"}
    ]
  }'

Python

python

# pip install openai
import os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ["ASKSHIVA_BASE_URL"],
    api_key=os.environ["ASKSHIVA_API_KEY"],
)

reply = client.chat.completions.create(
    model="askshiva-smart",
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "What does an AI gateway do?"},
    ],
)
print(reply.choices[0].message.content)

JavaScript

javascript

// npm install openai   (server-side code only, Node 18 or later)
import OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.ASKSHIVA_BASE_URL,
  apiKey: process.env.ASKSHIVA_API_KEY,
});

const reply = await client.chat.completions.create({
  model: "askshiva-smart",
  messages: [
    { role: "system", content: "Answer in two sentences." },
    { role: "user", content: "What does an AI gateway do?" },
  ],
});
console.log(reply.choices[0].message.content);

Stream the answer

Set stream to true to get server-sent events, ending with [DONE]. Long streams are allowed: see the per-alias timeouts on the aliases page.

curl

bash

curl -N "$ASKSHIVA_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $ASKSHIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "askshiva-fast", "stream": true,
       "messages": [{"role": "user", "content": "Three names for a tea shop."}]}'

Python

python

stream = client.chat.completions.create(
    model="askshiva-fast",
    messages=[{"role": "user", "content": "Three names for a tea shop."}],
    stream=True,
)
for chunk in stream:
    if chunk.choices and chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

JavaScript

javascript

const stream = await client.chat.completions.create({
  model: "askshiva-fast",
  messages: [{ role: "user", content: "Three names for a tea shop." }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content ?? "");
}

See your models

GET /models lists only the names your key may call. Asking for anything else returns HTTP 403.

curl

bash

curl "$ASKSHIVA_BASE_URL/models" \
  -H "Authorization: Bearer $ASKSHIVA_API_KEY"

Python

python

for m in client.models.list():
    print(m.id)

JavaScript

javascript

for await (const m of client.models.list()) {
  console.log(m.id);
}

Tool calls

askshiva-tool is the alias for function calling. The model returns the call; your code runs it.

Python

python

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Current weather for a city",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string"},
                "unit": {"type": "string", "enum": ["c", "f"]},
            },
            "required": ["city"],
        },
    },
}]

reply = client.chat.completions.create(
    model="askshiva-tool",
    messages=[{"role": "user", "content": "Weather in Pune, in Celsius?"}],
    tools=tools,
)
print(reply.choices[0].message.tool_calls)
# e.g. get_weather({"city": "Pune", "unit": "c"}): your code runs the tool

JavaScript

javascript

const tools = [{
  type: "function",
  function: {
    name: "get_weather",
    description: "Current weather for a city",
    parameters: {
      type: "object",
      properties: {
        city: { type: "string" },
        unit: { type: "string", enum: ["c", "f"] },
      },
      required: ["city"],
    },
  },
}];

const reply = await client.chat.completions.create({
  model: "askshiva-tool",
  messages: [{ role: "user", content: "Weather in Pune, in Celsius?" }],
  tools,
});
console.log(reply.choices[0].message.tool_calls);

Structured JSON

For strict JSON, send a JSON schema with response_format. askshiva-tool is the alias tested for this.

Python

python

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "integer"},
        "city": {"type": "string"},
    },
    "required": ["name", "age", "city"],
    "additionalProperties": False,
}

reply = client.chat.completions.create(
    model="askshiva-tool",
    messages=[{"role": "user", "content": "Ravi Kumar is 34 and lives in Nagpur."}],
    response_format={
        "type": "json_schema",
        "json_schema": {"name": "person", "strict": True, "schema": schema},
    },
)
print(reply.choices[0].message.content)
# {"name": "Ravi Kumar", "age": 34, "city": "Nagpur"}

JavaScript

javascript

const reply = await client.chat.completions.create({
  model: "askshiva-tool",
  messages: [{ role: "user", content: "Ravi Kumar is 34 and lives in Nagpur." }],
  response_format: {
    type: "json_schema",
    json_schema: {
      name: "person",
      strict: true,
      schema: {
        type: "object",
        properties: {
          name: { type: "string" },
          age: { type: "integer" },
          city: { type: "string" },
        },
        required: ["name", "age", "city"],
        additionalProperties: false,
      },
    },
  },
});
console.log(JSON.parse(reply.choices[0].message.content));

Embeddings

askshiva-embed returns 1,536-dimension vectors. Do not mix vectors from different embedding aliases in one index: see local aliases.

curl

bash

curl "$ASKSHIVA_BASE_URL/embeddings" \
  -H "Authorization: Bearer $ASKSHIVA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "askshiva-embed", "input": ["first text", "second text"]}'

Python

python

emb = client.embeddings.create(
    model="askshiva-embed",
    input=["first text", "second text"],
)
print(len(emb.data[0].embedding))   # 1536 for askshiva-embed

JavaScript

javascript

const emb = await client.embeddings.create({
  model: "askshiva-embed",
  input: ["first text", "second text"],
});
console.log(emb.data[0].embedding.length); // 1536 for askshiva-embed

Ground rules

Server-side only. Never put the key in a browser bundle, a mobile app or a desktop installer. Anyone who has it can spend your budget.
Send only the data your key’s class allows. A key cleared for public data must not carry personal data. See data classes.
Handle errors. 401, 403 and 429 are normal answers; see errors.
Leaked a key? Tell us through askshiva.in and we will replace it.