Public API reference

API Documentation

A structured guide for beginners, developers, and AI coding agents. Use one Ezkielyna endpoint for apps, automations, coding assistants, router tools, and custom backends.

Start here

Quick Start

Ezkielyna API follows a familiar chat-completions request format. Most integrations only need the base URL, API key, and an approved Ezkielyna model alias.

Create account

Create API key

Go to API Keys, create a key, then store it securely.

Send request

Use the base URL, model alias, and Bearer token.

Base URL

https://api-ezkielyna.tech/api/v1

Authorization header

Authorization: Bearer ez-your-api-key-here

Create account Open dashboard

First API call

bash

curl -X POST https://api-ezkielyna.tech/api/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ez-your-api-key-here" \
  -d '{
    "model": "ez-chat-standard",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Explain API gateways in simple terms."}
    ],
    "temperature": 0.7,
    "max_tokens": 500
  }'

Example response

json

{
  "id": "chatcmpl_abc123",
  "object": "chat.completion",
  "created": 1716000000,
  "model": "ez-chat-standard",
  "choices": [{
    "index": 0,
    "message": {"role": "assistant", "content": "An API gateway is a single entry point..."},
    "finish_reason": "stop"
  }],
  "usage": {"prompt_tokens": 28, "completion_tokens": 132, "total_tokens": 160}
}

Keys and security

Authentication

Every request must include a Bearer token. API keys are shown once, so copy the key into a secure secret manager or environment variable immediately after creation.

http

Authorization: Bearer ez-your-api-key-here

Security warning

Do not expose API keys in browser code, mobile apps, screenshots, repositories, or public logs. For web products, send requests from your server and keep the key in server-side environment variables.

Recommended key workflow

Create one key per environment, such as development, staging, and production.
Name keys clearly so you can revoke the right key during an incident.
Rotate keys regularly and immediately after a leak is suspected.
Use dashboard usage records to monitor unusual traffic, cost, and latency.

Use anywhere

Agents and SDKs

Use Ezkielyna with any tool that supports standard chat-completions style requests. The important fields are the same: base URL, API key, model alias, and optional temperature or token limits.

Coding assistants and developer tools

Paste the Ezkielyna base URL, enter your API key, then choose an alias such as ez-chat-fast for daily tasks or ez-reasoning for deeper analysis.

Routers, agent runtimes, and custom backends

Register Ezkielyna as a private model endpoint. Keep your Ezkielyna key server-side and expose only your own internal key to end users or team members.

Universal environment variables

dotenv

EZKIELYNA_API_KEY="ez-your-api-key-here"
EZKIELYNA_BASE_URL="https://api-ezkielyna.tech/api/v1"
DEFAULT_MODEL="ez-chat-fast"
REASONING_MODEL="ez-reasoning"
LONG_CONTEXT_MODEL="ez-long-context"

Router configuration example

yaml

routes:
  - name: ez-chat-standard
    base_url: https://api-ezkielyna.tech/api/v1
    api_key_env: EZKIELYNA_API_KEY
  - name: ez-reasoning
    base_url: https://api-ezkielyna.tech/api/v1
    api_key_env: EZKIELYNA_API_KEY

Reference

API Endpoints

All endpoints return JSON unless streaming is enabled. Keep request bodies under the published size limits and set Content-Type: application/json.

Method	Endpoint	Purpose
GET	/models	List model aliases available to your account.
POST	/chat/completions	Primary chat endpoint for assistants, agents, tools, and apps.
POST	/completions	Legacy text completion endpoint for older SDKs.
POST	/embeddings	Vector embeddings for search, RAG, and clustering.
POST	/images/generations	Image generation when enabled for your tier.

Streaming responses

Add "stream": true to receive server-sent events.

javascript

const stream = await client.chat.completions.create({
  model: "ez-long-context",
  messages: [{ role: "user", content: "Write a concise deployment checklist." }],
  stream: true,
});

for await (const chunk of stream) {
  const content = chunk.choices[0]?.delta?.content || "";
  process.stdout.write(content);
}

Tool and function calling

Use the standard tool schema for agents that need structured actions.

javascript

const response = await client.chat.completions.create({
  model: "ez-chat-standard",
  messages: [{ role: "user", content: "Create a support ticket for a failed payment." }],
  tools: [{
    type: "function",
    function: {
      name: "create_ticket",
      description: "Create a support ticket",
      parameters: {
        type: "object",
        properties: {
          subject: { type: "string" },
          priority: { type: "string", enum: ["low", "medium", "high"] }
        },
        required: ["subject", "priority"]
      }
    }
  }]
});

Abstraction layer

Models and Routing

Your application should depend on Ezkielyna model aliases, not on private routing details. Ezkielyna is the visible API surface, while capacity partners, credentials, and server placement remain internal.

General purpose

ez-chat-standardez-chat-fastez-chat-pro

Reasoning and coding

ez-reasoningez-codeez-build

Fast and low cost

ez-fastez-miniez-efficient

Specialized

embeddingsimage-generationlong-context

Smart routing

Requests are routed through managed capacity based on model, account tier, availability, and failover rules.

Routing privacy

Public responses should not expose private account names, internal server names, API keys, or routing credentials.

Failover behavior

If a route is temporarily unavailable, retry with backoff or switch to another approved alias.

Reliability

Errors and Retries

Handle errors by status code. Production apps should log request IDs, apply backoff, and avoid infinite retry loops.

json

{
  "error": {"message": "Insufficient balance to process this request.", "type": "insufficient_balance", "code": 402}
}

Code	Meaning	Recommended action
400	Bad request	Validate JSON, model name, message format, and token limits.
401	Unauthorized	Check the Authorization header and confirm the API key is active.
402	Insufficient balance	Top up balance or reduce token usage before retrying.
403	Access denied	Use an allowed model or upgrade the account tier.
404	Endpoint or model not found	Confirm the endpoint path and model alias.
408	Timeout	Retry with backoff, lower max_tokens, or use streaming.
429	Rate limited	Respect Retry-After and apply exponential backoff.
500	Server error	Retry safely. Contact support if repeated.
502	Route temporarily unavailable	Retry with backoff or switch to another model alias.

Cost control

Billing and Usage

Ezkielyna uses pay-as-you-go credits. Each request records model, token usage, latency, and cost so you can monitor spend from the dashboard.

How billing works

Top up account balance from the dashboard.
Send requests using your API key.
Credits are deducted based on token usage and model pricing.
Review usage, costs, and exports from the dashboard.

Usage tracking

Token consumption by model.
Daily and weekly usage trends.
Recent request history with latency.
CSV export for finance and audits.

Before launch

Production Checklist

Security

Store keys in environment variables, rotate keys, avoid browser exposure, and keep separate keys per environment.

Reliability

Add timeouts, retry budgets, backoff, streaming for long outputs, and graceful fallback models.

Budget

Set internal user quotas, monitor balance, and alert before credits run low.

Observability

Log endpoint, model, latency, status code, and your own request ID without logging secrets or full sensitive prompts.

Minimal production setup

Server-side API key, explicit timeout, retry with backoff, usage monitoring, low-balance alerts, and a documented incident process for key rotation.