REST API

HTTP endpoints, schemas, status codes, and examples.

#Conventions

Base URL	`https://elektric.ai/v1`
Authentication	`Authorization: Bearer $ELEKTRIC_API_KEY`
Request ID	`x-elektric-request-id`
Pagination	`cursor` / `next_cursor`
Money	Exact decimal USD strings
Time	UTC ISO 8601

#Inference

#POST /v1/chat/completions

Create native or compatible chat.

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"messages":[{"role":"user","content":"Hello"}],"user_id":"user_123","conversation_id":"thread_123","stream":false}

Response

JSON

{"id":"req_…","choices":[{"message":{"role":"assistant","content":"Hello!"}}],"usage":{"prompt_tokens":12,"completion_tokens":4}}

Success: 200 unless noted. Errors: invalid_request, tool_disabled, rate_limit_error, billing_error.

#POST /v1/embeddings

Create vectors for a string or batch.

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"input":["red shoes","blue boots"]}

Response

JSON

{"data":[{"index":0,"embedding":[0.01]}],"model":"elektric-auto","dimensions":1536}

Success: 200 unless noted. Errors: invalid_request, rate_limit_error, billing_error.

#Context

#GET/PATCH/DELETE /v1/memory/:memoryId

Read, correct, or deactivate Memory. List with GET /v1/memory?user_id=….

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"query":{"user_id":"user_123"},"patch":{"summary":"User is building Orion."}}

Response

JSON

{"id":"mem_…","user_id":"user_123","summary":"User is building Orion.","status":"active"}

Success: 200 unless noted. Errors: invalid_user_id, memory_not_found.

#POST/GET/DELETE /v1/knowledge

Upload, list, inspect, or delete persistent sources.

Authentication: Project API key · Standard errors · Billing

Request

JSON

multipart/form-data: file=@handbook.md

Response

JSON

{"id":"ks_…","name":"handbook.md","status":"processing"}

Success: 200 unless noted. Errors: invalid_file, payload_too_large, knowledge_not_found.

#Media and realtime

#POST /v1/images/generations

Generate an Image Asset; edits use /v1/images/edits.

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"prompt":"A kite over the ocean","size":"square","format":"jpeg"}

Response

JSON

{"id":"img_…","images":[{"asset_id":"asset_…"}],"usage":{"images":1}}

Success: 200 unless noted. Errors: invalid_request, asset_expired, billing_error.

#POST /v1/video/generations

Start a Video Job; analysis uses /v1/video/analyze.

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"prompt":"Ocean waves","duration":"4s","aspect_ratio":"16:9","idempotency_key":"video-42"}

Response

JSON

{"id":"job_…","status":"queued","type":"video_generation"}

Success: 200 unless noted. Errors: invalid_request, asset_expired, billing_error.

#POST /v1/realtime/sessions

Create a short-lived WebSocket session.

Authentication: Project API key · Standard errors · Billing

Request

JSON

{"input":["text","audio"],"output":["text","audio"]}

Response

JSON

{"id":"rt_…","status":"created","connection":{"url":"wss://…"},"expires_at":"…"}

Success: 200 unless noted. Errors: invalid_request, rate_limit_error.

#Operations

Resource	Endpoints	Purpose
Files	`POST /v1/files · GET/DELETE /v1/files/:id`	Temporary uploads
Assets	`GET/DELETE /v1/assets/:id`	Metadata, bytes, deletion
Jobs	`GET /v1/jobs/:id · POST /v1/jobs/:id/cancel`	Status and cancellation
Requests	`GET /v1/requests · /v1/requests/:id`	Safe telemetry
Usage	`GET /v1/usage · /v1/usage/timeseries`	Usage summaries
Billing	`GET /v1/billing · /v1/billing/transactions`	Balance and ledger
Limits	`GET /v1/limits`	Effective policy
Embedding profiles	`POST/GET/PATCH /v1/embedding-profiles`	Vector profiles

#cURL example

cURL

curl https://elektric.ai/v1/chat/completions   -H "Authorization: Bearer $ELEKTRIC_API_KEY"   -H "Content-Type: application/json"   -d '{"messages":[{"role":"user","content":"Hello"}],"user_id":"user_123","conversation_id":"thread_123"}'