{"openapi":"3.1.0","info":{"title":"ewpire API","version":"v1","description":"The text models in the ewpire catalog through one endpoint, one key and one credit balance, in the OpenAI chat completions format.\n\nThe version is the `/v1` in the address. How the API changes is described at https://ewpire.com/docs/versioning, and changes are listed at https://ewpire.com/changelog.\n\nAPI keys are not open yet; the docs are published, so an integration can be planned now.","termsOfService":"https://ewpire.com/terms"},"externalDocs":{"description":"ewpire API documentation","url":"https://ewpire.com/docs"},"servers":[{"url":"https://ewpire.com/api/v1"}],"security":[{"apiKey":[]}],"paths":{"/chat/completions":{"post":{"operationId":"createChatCompletion","summary":"Create a chat completion","description":"Takes the OpenAI chat completions body and returns an OpenAI chat completion, streamed or not. A parameter the API does not support is refused with `400 unsupported_parameter`, not ignored. See https://ewpire.com/docs/chat.","parameters":[{"name":"Idempotency-Key","in":"header","required":false,"description":"A unique value per request, in visible ASCII characters. A repeat with the same body within 24 hours returns the first answer and is not charged again; the same key with another body is refused.","schema":{"type":"string","minLength":1,"maxLength":255}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletionRequest"}}}},"responses":{"200":{"description":"The completion. With `stream: true` the answer is server-sent events: `data:` lines that each carry one chunk, ending with `data: [DONE]`. A streamed answer carries no cost headers: with `stream_options.include_usage` the cost comes in the last chunk. If the answer fails after the stream has started, one `data:` line carries an error object and the stream ends.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"},"X-Ewpire-Credits-Charged":{"$ref":"#/components/headers/CreditsCharged"},"X-Ewpire-Balance":{"$ref":"#/components/headers/Balance"},"Idempotent-Replayed":{"$ref":"#/components/headers/IdempotentReplayed"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChatCompletion"}},"text/event-stream":{"schema":{"$ref":"#/components/schemas/ChatCompletionChunk"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}},"/models":{"get":{"operationId":"listModels","summary":"List the models the API serves","description":"Every model that can be called through the API, in the OpenAI list format with capabilities and prices in credits. The first entry is `auto`. See https://ewpire.com/docs/models.","responses":{"200":{"description":"The model list.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ModelList"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Read the API usage of the key's workspace","description":"Totals, one entry per day and one per model. Pass `range`, or `from` and `to`. See https://ewpire.com/docs/usage.","parameters":[{"name":"range","in":"query","required":false,"description":"The last so many days, today included (UTC).","schema":{"type":"integer","enum":[7,30,90],"default":30}},{"name":"from","in":"query","required":false,"description":"First day, UTC, included. Sent together with `to`.","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Last day, UTC, included. Sent together with `from`.","schema":{"type":"string","format":"date"}}],"responses":{"200":{"description":"The usage report.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageReport"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/TooManyRequests"},"default":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An ewpire API key, sent as `Authorization: Bearer <key>`. A key belongs to one workspace and spends that workspace's credits."}},"headers":{"RateLimitLimit":{"description":"Requests allowed per minute for this key.","schema":{"type":"integer"}},"RateLimitRemaining":{"description":"Requests left in the current minute.","schema":{"type":"integer"}},"RateLimitReset":{"description":"When the minute resets, in Unix seconds.","schema":{"type":"integer"}},"RequestId":{"description":"The id of the request in your usage records.","schema":{"type":"string"}},"CreditsCharged":{"description":"What this request cost, in credits with six decimals. Not on a streamed answer.","schema":{"type":"string"}},"Balance":{"description":"Credits available after the request, with six decimals. Not on a streamed answer.","schema":{"type":"string"}},"IdempotentReplayed":{"description":"`true` on a repeat answered from the first request with the same Idempotency-Key.","schema":{"type":"string"}},"RetryAfter":{"description":"Seconds to wait before the next request.","schema":{"type":"integer"}},"ShouldRetry":{"description":"`false` on a refusal that waiting cannot fix.","schema":{"type":"string"}}},"responses":{"Unauthorized":{"description":"The key is missing, wrong or revoked (`invalid_api_key`).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"TooManyRequests":{"description":"Too many requests per minute for this key (`rate_limit_exceeded`, with `Retry-After`), or a refusal that waiting cannot fix: not enough credits (`insufficient_quota`) or a spend limit reached (`spend_limit_exceeded`), both with `x-should-retry: false`.","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/RateLimitLimit"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/RateLimitRemaining"},"X-RateLimit-Reset":{"$ref":"#/components/headers/RateLimitReset"},"Retry-After":{"$ref":"#/components/headers/RetryAfter"},"x-should-retry":{"$ref":"#/components/headers/ShouldRetry"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error":{"description":"Any other refusal or failure, in the same format. The statuses and codes are listed at https://ewpire.com/docs/errors.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"ChatCompletionRequest":{"type":"object","required":["model","messages"],"additionalProperties":false,"properties":{"model":{"type":"string","minLength":1,"maxLength":200,"description":"A model id from `GET /models`, or `\"auto\"`."},"messages":{"type":"array","minItems":1,"maxItems":1000,"items":{"$ref":"#/components/schemas/ChatMessage"}},"stream":{"type":"boolean","default":false},"stream_options":{"type":"object","properties":{"include_usage":{"type":"boolean","description":"Adds a last chunk with token usage and what the request cost."}}},"max_tokens":{"type":"integer","minimum":1,"maximum":65536,"default":8192},"max_completion_tokens":{"type":"integer","minimum":1,"maximum":65536,"description":"Read in place of `max_tokens` when both are sent."},"temperature":{"type":"number","minimum":0,"maximum":2},"tools":{"type":"array","maxItems":128,"items":{"$ref":"#/components/schemas/Tool"}},"tool_choice":{"oneOf":[{"enum":["auto","none","required"]},{"type":"object","required":["type","function"],"properties":{"type":{"const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"}}}}}]},"response_format":{"oneOf":[{"type":"object","required":["type"],"properties":{"type":{"enum":["text","json_object"]}}},{"type":"object","required":["type","json_schema"],"properties":{"type":{"const":"json_schema"},"json_schema":{"type":"object","required":["name","schema"],"properties":{"name":{"type":"string"},"schema":{"type":"object","additionalProperties":true},"strict":{"type":"boolean"}}}}}]},"n":{"const":1},"top_p":{"const":1,"description":"Accepted at this value only; it changes nothing."},"frequency_penalty":{"const":0,"description":"Accepted at this value only; it changes nothing."},"presence_penalty":{"const":0,"description":"Accepted at this value only; it changes nothing."},"logprobs":{"const":false,"description":"Accepted at this value only; it changes nothing."},"user":{"type":"string","description":"Accepted; it changes nothing."},"parallel_tool_calls":{"type":"boolean","description":"Accepted; it changes nothing."}}},"ChatMessage":{"type":"object","required":["role"],"properties":{"role":{"enum":["system","developer","user","assistant","tool"],"description":"`developer` is read as `system`."},"content":{"type":["string","array","null"],"items":{"$ref":"#/components/schemas/ContentPart"}},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"},"description":"On an `assistant` message."},"tool_call_id":{"type":"string","description":"Required on a `tool` message."}}},"ContentPart":{"oneOf":[{"type":"object","required":["type","text"],"properties":{"type":{"const":"text"},"text":{"type":"string"}}},{"type":"object","required":["type","image_url"],"properties":{"type":{"const":"image_url"},"image_url":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"A link or a `data:` URL."}}}}}]},"Tool":{"type":"object","required":["type","function"],"properties":{"type":{"const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"parameters":{"type":"object","additionalProperties":true}}}}},"ToolCall":{"type":"object","required":["id","function"],"properties":{"id":{"type":"string"},"type":{"const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"arguments":{"type":"string","description":"The arguments as a JSON string."}}}}},"ChatCompletion":{"type":"object","required":["id","object","created","model","choices","usage"],"properties":{"id":{"type":"string"},"object":{"const":"chat.completion"},"created":{"type":"integer","description":"Unix seconds."},"model":{"type":"string","description":"The model that answered; under `auto`, the one ewpire picked."},"choices":{"type":"array","items":{"type":"object","required":["index","message","logprobs","finish_reason"],"properties":{"index":{"type":"integer"},"message":{"type":"object","required":["role","content","refusal"],"properties":{"role":{"const":"assistant"},"content":{"type":["string","null"]},"refusal":{"type":"null"},"tool_calls":{"type":"array","items":{"$ref":"#/components/schemas/ToolCall"}}}},"logprobs":{"type":"null"},"finish_reason":{"$ref":"#/components/schemas/FinishReason"}}}},"usage":{"$ref":"#/components/schemas/TokenUsage"}}},"ChatCompletionChunk":{"type":"object","required":["id","object","created","model","choices"],"properties":{"id":{"type":"string"},"object":{"const":"chat.completion.chunk"},"created":{"type":"integer","description":"Unix seconds."},"model":{"type":"string"},"choices":{"type":"array","description":"Empty in the usage chunk.","items":{"type":"object","required":["index","delta","logprobs","finish_reason"],"properties":{"index":{"type":"integer"},"delta":{"type":"object","properties":{"role":{"const":"assistant"},"content":{"type":"string"},"tool_calls":{"type":"array","items":{"type":"object","required":["index","id","function"],"properties":{"index":{"type":"integer"},"id":{"type":"string"},"type":{"const":"function"},"function":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"arguments":{"type":"string","description":"The arguments as a JSON string."}}}}}}}},"logprobs":{"type":"null"},"finish_reason":{"oneOf":[{"$ref":"#/components/schemas/FinishReason"},{"type":"null"}]}}}},"usage":{"$ref":"#/components/schemas/TokenUsage"},"ewpire":{"type":"object","description":"In the usage chunk: what the request cost and what is left.","required":["credits_charged","balance"],"properties":{"credits_charged":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Credits as a decimal with six places.","examples":["0.000262"]},"balance":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Credits as a decimal with six places.","examples":["0.000262"]}}}}},"FinishReason":{"enum":["stop","length","tool_calls","content_filter"]},"TokenUsage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"prompt_tokens_details":{"type":"object","properties":{"cached_tokens":{"type":"integer"}}},"completion_tokens_details":{"type":"object","properties":{"reasoning_tokens":{"type":"integer"}}}}},"ModelList":{"type":"object","required":["object","data"],"properties":{"object":{"const":"list"},"data":{"type":"array","items":{"$ref":"#/components/schemas/Model"}}}},"Model":{"type":"object","required":["id","object","created","owned_by","name","description"],"properties":{"id":{"type":"string","description":"What you pass as `model`."},"object":{"const":"model"},"created":{"const":0,"description":"The catalog does not keep release dates."},"owned_by":{"type":"string","description":"The lab that makes the model."},"name":{"type":"string"},"description":{"type":["string","null"]},"context_length":{"type":["integer","null"],"description":"The most tokens the model takes in one request."},"capabilities":{"type":"array","items":{"type":"string"}},"input_modalities":{"type":"array","items":{"type":"string"}},"output_modalities":{"type":"array","items":{"type":"string"}},"pricing":{"type":"object","required":["input_credits_per_million_tokens","output_credits_per_million_tokens"],"properties":{"input_credits_per_million_tokens":{"type":["number","null"]},"output_credits_per_million_tokens":{"type":["number","null"]},"long_context":{"type":"array","description":"Only on a model that charges long requests at a higher rate, lowest threshold first: a request whose input reaches `min_prompt_tokens` is charged whole at that entry's rates.","items":{"type":"object","required":["min_prompt_tokens","input_credits_per_million_tokens","output_credits_per_million_tokens"],"properties":{"min_prompt_tokens":{"type":"integer"},"input_credits_per_million_tokens":{"type":"number"},"output_credits_per_million_tokens":{"type":"number"}}}}}}}},"UsageReport":{"type":"object","required":["object","from","to","totals","days","models"],"properties":{"object":{"const":"usage"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"totals":{"type":"object","required":["requests","errors","prompt_tokens","completion_tokens","total_tokens","credits","median_latency_ms"],"properties":{"requests":{"type":"integer"},"errors":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"credits":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Credits as a decimal with six places.","examples":["0.000262"]},"median_latency_ms":{"type":["integer","null"],"description":"Median duration of a request, in milliseconds; null without requests."}}},"days":{"type":"array","description":"One entry per day of the range, days without requests included.","items":{"type":"object","required":["date","requests","errors","prompt_tokens","completion_tokens","total_tokens","credits"],"properties":{"date":{"type":"string","format":"date"},"requests":{"type":"integer"},"errors":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"credits":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Credits as a decimal with six places.","examples":["0.000262"]}}}},"models":{"type":"array","items":{"type":"object","required":["model","requests","errors","prompt_tokens","completion_tokens","total_tokens","credits","median_latency_ms"],"properties":{"model":{"type":"string"},"requests":{"type":"integer"},"errors":{"type":"integer"},"prompt_tokens":{"type":"integer"},"completion_tokens":{"type":"integer"},"total_tokens":{"type":"integer"},"credits":{"type":"string","pattern":"^-?\\d+\\.\\d{6}$","description":"Credits as a decimal with six places.","examples":["0.000262"]},"median_latency_ms":{"type":["integer","null"],"description":"Median duration of a request, in milliseconds; null without requests."}}}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["message","type","param","code"],"properties":{"message":{"type":"string"},"type":{"type":"string"},"param":{"type":["string","null"],"description":"The field at fault, when there is one."},"code":{"type":["string","null"],"description":"What happened, for a program to read. The codes are listed at https://ewpire.com/docs/errors; new ones can be added."}}}}}}}}