API versioning

The Mira API uses URL-based versioning to ensure backward compatibility and smooth migration between versions. The current stable version is v1.

Current version

https://api.vmira.ai/v1

All endpoints include the version in the URL path. For example:

How versioning works

The API version is specified directly in the URL path (e.g., /v1/). This means different API versions can coexist simultaneously, allowing gradual migration.

• URL-based — The version is part of the URL: /v1/chat/completions. When v2 is released, the URL will be /v2/chat/completions.
• No implicit versions — Requests without a version in the URL are not supported. Always specify the version explicitly.
• Default version — Currently the only available version is v1. When new versions are released, v1 will continue to work.

Backward compatibility policy

Mira follows a strict backward compatibility policy within a major version:

• Non-breaking changes — Adding new fields to responses, new optional request parameters, and new endpoints — these changes do not require client code updates.
• Breaking changes — Removing fields, changing types, renaming parameters, and behavior changes — these are only possible in a new major version (v2).

Deprecation notices

If an API version is scheduled for removal, Mira provides at least 12 months for migration:

• Announcement — A deprecation notice is published in the documentation, blog, and sent via email to all users with active keys.
• Migration period — The old version continues to work for at least 12 months after the announcement. During this period you can update your code.
• Warning headers — Responses from a deprecated version will include a Deprecation header with the removal date.
• Removal — After the migration period ends, the old version returns a 410 Gone error.

HTTP/1.1 200 OK
Deprecation: Sun, 01 Jan 2028 00:00:00 GMT
Sunset: Sun, 01 Jan 2028 00:00:00 GMT
Link: <https://docs.vmira.ai/migration/v1-to-v2>; rel="deprecation"

Migration from OpenAI

The Mira API is fully compatible with the OpenAI format. If you already use the OpenAI API or SDK, migration requires minimal effort — just change the base URL and API key.

Using the OpenAI SDK

from openai import OpenAI

# Before (OpenAI)
# client = OpenAI(api_key="sk-...")

# After (Mira) — just change base_url and api_key
client = OpenAI(
    base_url="https://api.vmira.ai/v1",
    api_key="sk-mira-your-key-here",
)

response = client.chat.completions.create(
    model="mira",  # Use a Mira model name
    messages=[{"role": "user", "content": "Hello, Mira!"}],
)

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

import OpenAI from "openai";

// Before (OpenAI)
// const client = new OpenAI({ apiKey: "sk-..." });

// After (Mira) — just change baseURL and apiKey
const client = new OpenAI({
  baseURL: "https://api.vmira.ai/v1",
  apiKey: "sk-mira-your-key-here",
});

const response = await client.chat.completions.create({
  model: "mira",  // Use a Mira model name
  messages: [{ role: "user", content: "Hello, Mira!" }],
});

console.log(response.choices[0].message.content);

Migration changes

Migration via environment variables

For quick migration, you can use environment variables without changing application code:

# Replace in your .env file
OPENAI_API_KEY=sk-mira-your-key-here
OPENAI_BASE_URL=https://api.vmira.ai/v1

Next steps