Developer Reference

Eikr API Docs

Integrate Eikr's AI engine into your product. All requests are HTTPS, JSON in and out. Base URL: https://api.eikr.ee

Authentication

Every request to a protected endpoint must include your API key in the request header. API keys are issued after signing up for an API plan.

Header
X-API-Key: eikr_your_api_key_here
Keep your key secret. Never expose it in client-side code or commit it to version control. If compromised, contact us immediately to rotate it.

Chat Endpoint

Send a message and receive an AI-generated response. Supports custom personas, conversation history, and per-user memory injection.

POST /chat

Request body

ParameterTypeDescription
messagerequiredstringThe user's message text
personalityoptionalstringSystem prompt / persona definition for the AI
historyoptionalarrayPrevious messages as [{role, content}] for context
user_idoptionalstringYour user identifier for memory persistence
languageoptionalstringResponse language code e.g. "en", "es", "pt"
Request example
const res = await fetch("https://api.eikr.ee/chat", {
  method: "POST",
  headers: {
    "X-API-Key": "eikr_your_key",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    message: "What are your opening hours?",
    personality: "You are Sofia, support agent for Acme Store.",
    user_id: "user_123"
  })
});
Response
{
  "reply": "Hi! Our store is open Monday–Friday, 9am–6pm CET.",
  "tokens_used": 84,
  "model": "gpt-4o-mini"
}

Streaming Responses

For real-time chat experiences, use the streaming endpoint. Responses are delivered as Server-Sent Events (SSE). Same parameters as /chat.

POST /chat/stream
Streaming example
const res = await fetch("https://api.eikr.ee/chat/stream", {
  method: "POST",
  headers: { "X-API-Key": "eikr_your_key", "Content-Type": "application/json" },
  body: JSON.stringify({ message: "Tell me about Tallinn" })
});

const reader = res.body.getReader();
const decoder = new TextDecoder();

while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  const chunk = decoder.decode(value);
  process.stdout.write(chunk); // stream tokens as they arrive
}

Voice Input

Transcribe a voice message (audio file) to text using Eikr's speech recognition pipeline.

POST /voice

Send audio as multipart/form-data with the file in the audio field. Supported formats: .ogg, .mp3, .wav, .m4a

Response
{ "transcript": "What time do you close today?", "language": "en" }

Text-to-Speech

Convert a text string to an audio file. Useful for voice response loops.

POST /tts
ParameterTypeDescription
textrequiredstringText to convert to speech
voiceoptionalstring"alloy" (default), "nova", "echo", "fable", "onyx", "shimmer"
languageoptionalstringLanguage code for pronunciation

Returns an audio/mpeg binary stream.

Vision / Image Analysis

Analyze an image and get an AI description or answer questions about it.

POST /vision
ParameterTypeDescription
image_urlrequired*stringPublicly accessible URL of the image
image_base64required*stringBase64-encoded image (alternative to URL)
questionoptionalstringSpecific question about the image

* Provide either image_url or image_base64, not both.

Error Codes

CodeMeaning
400Bad request — missing or invalid parameters
401Unauthorized — missing or invalid API key
429Rate limit exceeded — slow down requests
500Internal server error — retry after a moment

Rate Limits

Rate limits are applied per API key, based on your plan's monthly request allowance. Hitting a rate limit returns a 429 response.

For burst usage or higher limits, contact us — we can accommodate most use cases.