AshnaAI API

The AshnaAI HTTP API speaks three client protocols on one host: OpenAI Chat Completions, Anthropic Messages (Claude Code), and OpenAI Responses (Codex). Use the same Account → API key. Point the client at https://api.ashna.ai/v1/api and set model to a foundation model id or your Ashna custom agent id.

What's supported

Three request shapes on the same host. Chat Completions is verified with ai + @ai-sdk/openai. Claude Code posts Anthropic Messages. Codex posts OpenAI Responses.

• OpenAI Chat Completions — POST /chat/completions (Cursor, VS Code, Cline, Continue, SDKs)
• Anthropic Messages — POST /v1/messages (Claude Code)
• OpenAI Responses — POST /responses (Codex)
• Foundation models via model (for example glm-5.3, claude-sonnet-5, claude-opus-5, claude-fable-5, gpt-4o-mini, Ashna models)
• Custom Ashna agents via model or agent_id (server-side multi-step tools)
• Client tools (tools / tool_choice) with tool_calls round-trips
• Sampling: temperature, top_p / top_k, penalties, stop, seed, max_tokens / max_completion_tokens
• Structured output: response_format json_object and json_schema
• OpenAI-compatible streaming SSE ([DONE], usage, tool call deltas)
• Optional Ashna UI data stream via streamType: "data"
• Vision images and PDF attachments (provider-aware: native PDF vs text extract)
• OpenAI error envelope { error: { message, type, code, param } }
• GET /models catalog

Quickstart

Create a key, then call Chat Completions with an OpenAI-compatible client — or point Claude Code at the same host with ANTHROPIC_BASE_URL.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const { text } = await generateText({
  model: ashnaAI.chat("gpt-4o-mini"),
  messages: [
    { role: 'user', content: "Hello, can you help me?" }
  ],
  maxOutputTokens: 500,
  temperature: 0.7,
});
 
console.log(text);

Model IDs & agent IDs

Chat Completions uses a single model field. Pass either a foundation model id or your custom agent id. You can also send agent_id when model is omitted.

Supported foundation model ids

Use any of these values as model for foundation-model Chat Completions. Grouped by provider family (OpenAI, Anthropic, DeepSeek, Google, and others).

Authentication

All requests need the key from Account → API. OpenAI-compatible clients send a Bearer token. Claude Code sends the same secret as ANTHROPIC_API_KEY / x-api-key.

▸ curl https://api.ashna.ai/v1/api/models \
▸   -H "Authorization: Bearer YOUR_API_KEY"

▸ curl https://api.ashna.ai/v1/api/v1/messages \
▸   -H "x-api-key: YOUR_API_KEY" \
▸   -H "anthropic-version: 2023-06-01" \
▸   -H "Content-Type: application/json"

Try the API

Errors

Failures return an OpenAI-compatible envelope so SDKs can surface error.message consistently.

{
  "error": {
    "message": "Invalid API key provided.",
    "type": "invalid_request_error",
    "code": "invalid_api_key",
    "param": null
  }
}

API Endpoints

Primary integration path is OpenAI Chat Completions. Paths below are relative to https://api.ashna.ai/v1/api.

List Models

Returns foundation models available through the external API (OpenAI { object: "list", data } shape). Custom agents are not listed here—use your agent's customAgentId directly as model (see Model & agent IDs).

▸ curl https://api.ashna.ai/v1/api/models \
▸   -H "Authorization: Bearer YOUR_API_KEY"

{
  "object": "list",
  "data": [
    {
      "id": "gpt-4o-mini",
      "object": "model",
      "created": 1704369000,
      "owned_by": "openai"
    }
  ]
}

Chat Completions

Stateless OpenAI-compatible chat endpoint. Works with the OpenAI SDKs, Vercel AI SDK (generateText / streamText), Cursor, VS Code, Cline, and Continue. Claude Code does not use this path — it posts Anthropic Messages.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const { text } = await generateText({
  model: ashnaAI.chat("gpt-4o-mini"),
  messages: [
    { role: 'system', content: "You are a helpful assistant." },
    { role: 'user', content: "Explain quantum computing briefly." }
  ],
  maxOutputTokens: 500,
  temperature: 0.7,
});
 
console.log(text);

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "created": 1704369000,
  "model": "gpt-4o-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Quantum computing leverages quantum mechanics..."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 25,
    "completion_tokens": 120,
    "total_tokens": 145
  }
}

Messages (Claude Code)

Anthropic Messages–compatible endpoint. Claude Code posts here — not Chat Completions. Set ANTHROPIC_BASE_URL to https://api.ashna.ai/v1/api so the CLI posts /v1/messages on that host. Use aliases sonnet, opus, haiku, or a catalog id such as glm-5.3-flash. Step-by-step install and first turn: How to use the AshnaAI API in Claude Code.

▸ export ANTHROPIC_BASE_URL="https://api.ashna.ai/v1/api"
▸ export ANTHROPIC_API_KEY="YOUR_API_KEY"
▸ cd /path/to/your/project
▸ claude

▸ curl https://api.ashna.ai/v1/api/v1/messages \
▸   -H "x-api-key: YOUR_API_KEY" \
▸   -H "anthropic-version: 2023-06-01" \
▸   -H "Content-Type: application/json" \
▸   -d '{
▸     "model": "sonnet",
▸     "max_tokens": 256,
▸     "messages": [
▸       { "role": "user", "content": "Reply with exactly: ping" }
▸     ]
▸   }'

{
  "id": "msg_abc123",
  "type": "message",
  "role": "assistant",
  "model": "sonnet",
  "content": [
    { "type": "text", "text": "ping" }
  ],
  "stop_reason": "end_turn",
  "usage": { "input_tokens": 12, "output_tokens": 1 }
}

Responses (Codex)

OpenAI Responses–compatible endpoint. Codex CLI posts here — not Chat Completions. Set OPENAI_BASE_URL to https://api.ashna.ai/v1/api. OpenClaw can use the same path in openai-responses mode. Install and first turn: How to use the AshnaAI API in OpenClaw, Cline, and Codex.

▸ export OPENAI_BASE_URL="https://api.ashna.ai/v1/api"
▸ export OPENAI_API_KEY="YOUR_API_KEY"
▸ cd /path/to/your/project
▸ codex

▸ curl https://api.ashna.ai/v1/api/responses \
▸   -H "Authorization: Bearer YOUR_API_KEY" \
▸   -H "Content-Type: application/json" \
▸   -d '{
▸     "model": "glm-5.3-flash",
▸     "input": "Reply with exactly: ping"
▸   }'

Agents

Pass your Ashna custom agent id as model (or agent_id). The API loads that agent's prompt, foundation model, data sources, and tools, then runs a multi-step tool loop on the server (up to 200 steps)—similar to the Ashna web agent.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const { text } = await generateText({
  model: ashnaAI.chat("your-custom-agent-id"),
  messages: [
    { role: 'user', content: "Summarize today's priorities." }
  ],
  maxOutputTokens: 400,
  temperature: 0.7,
});
 
console.log(text);

▸ curl https://api.ashna.ai/v1/api/chat/completions \
▸   -H "Authorization: Bearer YOUR_API_KEY" \
▸   -H "Content-Type: application/json" \
▸   -d '{
▸     "agent_id": "your-custom-agent-id",
▸     "messages": [
▸       { "role": "user", "content": "Hello" }
▸     ]
▸   }'

Tools

Two modes:

• Client tools — send OpenAI tools / tool_choice on a foundation model. The API returns tool_calls (no server execute). You run the tool locally and send a follow-up with role: "tool" messages.
• Agent tools — when model is a custom agent, configured tools run on the server across multiple steps.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText, jsonSchema, tool } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const weather = tool({
  description: 'Get weather for a city',
  inputSchema: jsonSchema({
    type: 'object',
    properties: { city: { type: 'string' } },
    required: ['city'],
  }),
  execute: async ({ city }) => ({ city, tempC: 21 }),
});
 
const first = await generateText({
  model: ashnaAI.chat('gpt-4o-mini'),
  tools: { get_weather: weather },
  toolChoice: 'required',
  prompt: 'What is the weather in Paris? Use the tool.',
});
 
// first.toolCalls → execute locally → send tool results back in messages

Sampling & JSON output

import OpenAI from 'openai';
 
const client = new OpenAI({
  apiKey: process.env.ASHNA_API_KEY,
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
});
 
const response = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: 'user', content: "Return JSON with keys a=1 and b=\"x\"." }
  ],
  temperature: 0.2,
  max_tokens: 80,
  response_format: {"type":"json_object"},});
 
console.log(response.choices[0].message.content);

▸ curl https://api.ashna.ai/v1/api/chat/completions \
▸   -H "Authorization: Bearer YOUR_API_KEY" \
▸   -H "Content-Type: application/json" \
▸   -d '{
▸     "model": "gpt-4o-mini",
▸     "messages": [
▸       {
▸         "role": "user",
▸         "content": "Return a city weather sample."
▸       }
▸     ],
▸     "temperature": 0.2,
▸     "max_tokens": 120,
▸     "response_format": {
▸       "type": "json_schema",
▸       "json_schema": {
▸         "name": "weather_sample",
▸         "schema": {
▸           "type": "object",
▸           "additionalProperties": false,
▸           "properties": {
▸             "city": {
▸               "type": "string"
▸             },
▸             "tempC": {
▸               "type": "number"
▸             }
▸           },
▸           "required": [
▸             "city",
▸             "tempC"
▸           ]
▸         }
▸       }
▸     }
▸   }'

Images & PDFs

User messages may include OpenAI/AI SDK multimodal parts. Ashna routes attachments per foundation model provider:

• Images — kept as vision parts when the model allows image input; otherwise replaced with an explanatory text note.
• Native PDF — Gemini, Claude, Bedrock, Mistral, and Azure/OpenAI Responses models receive PDF file parts.
• PDF text extract — Azure Chat Completions (for example gpt-4o-mini), Groq, and many OpenAI-compatible hosts extract PDF text before the model call.

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
import { readFileSync } from 'fs';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const pdfBytes = readFileSync('./report.pdf');
 
const result = await generateText({
  model: ashnaAI.chat('gpt-4o-mini'),
  messages: [
    {
      role: 'user',
      content: [
        { type: 'text', text: 'Summarize this PDF and describe the image.' },
        { type: 'file', data: pdfBytes, mediaType: 'application/pdf', filename: 'report.pdf' },
        { type: 'image', image: readFileSync('./chart.png'), mediaType: 'image/png' },
      ],
    },
  ],
});

{
  "model": "gpt-4o-mini",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "What is in this image and PDF?" },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,..." }
        },
        {
          "type": "file",
          "file": {
            "filename": "hello.pdf",
            "file_data": "data:application/pdf;base64,..."
          }
        }
      ]
    }
  ]
}

Streaming

Set stream: true for OpenAI-compatible SSE (chat.completion.chunk events, ending with data: [DONE]).

import { createOpenAI } from '@ai-sdk/openai';
import { streamText } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const result = streamText({
  model: ashnaAI.chat("gpt-4o-mini"),
  messages: [
    { role: 'user', content: "Say hello in one short sentence." }
  ],
  maxOutputTokens: 100,
  temperature: 0.7,
});
 
for await (const chunk of result.textStream) {
  process.stdout.write(chunk);
}

data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"role":"assistant","content":""},"finish_reason":null}]}
 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{"content":"Hello"},"finish_reason":null}]}
 
data: {"id":"chatcmpl-...","object":"chat.completion.chunk","choices":[{"index":0,"delta":{},"finish_reason":"stop"}],"usage":{"prompt_tokens":12,"completion_tokens":4,"total_tokens":16}}
 
data: [DONE]

Completions (legacy alias)

POST /v1/api/completions uses the same pipeline as Chat Completions for SDK compatibility. Prefer /chat/completions. You can send prompt (string) or messages; the response shape is still a chat completion object from this shared pipeline.

▸ curl https://api.ashna.ai/v1/api/completions \
▸   -H "Authorization: Bearer YOUR_API_KEY" \
▸   -H "Content-Type: application/json" \
▸   -d '{
▸     "model": "gpt-4o-mini",
▸     "prompt": "Reply with exactly: ping",
▸     "max_tokens": 20
▸   }'

Editor & CLI guides

Point Cursor, Claude Code, Codex, VS Code, Cline, OpenClaw, or Continue at https://api.ashna.ai/v1/api. Create a key in Account → API. Claude Code uses POST /v1/messages; Codex uses POST /responses; Cursor and VS Code use POST /chat/completions.

SDKs & Integrations

OpenAI SDKs talk Chat Completions — only the base URL and API key change. Claude Code is an Anthropic Messages client: export ANTHROPIC_BASE_URL and ANTHROPIC_API_KEY, then see Messages (Claude Code) or the full walkthrough. Keys come from Account → API.

Install tips: npm i ai @ai-sdk/openai · npm i openai · pip install openai · go get github.com/openai/openai-go/v3 · OpenAI Java SDK via Maven/Gradle (com.openai:openai-java).

import { createOpenAI } from '@ai-sdk/openai';
import { generateText } from 'ai';
 
const ashnaAI = createOpenAI({
  baseURL: 'https://api.ashna.ai/v1/api'//api.ashna.ai/v1/api',
  apiKey: process.env.ASHNA_API_KEY,
});
 
const { text } = await generateText({
  model: ashnaAI.chat("gpt-4o-mini"),
  messages: [
    { role: 'user', content: "Hello!" }
  ],
  maxOutputTokens: 100,
  temperature: 0.2,
});
 
console.log(text);