API endpoint reference

Use https://api.cloakray.com with a project API key from the console. Send Authorization: Bearer $CLOAKRAY_API_KEY; do not put keys in URLs. The examples below use MODEL for a canonical model ID supporting that endpoint, chosen from models.

This reference describes API contracts, not a claim that every listed model, format or transport is enabled. Check the model's supported endpoints and your workspace's entitlements. A registered route is not proof of a completed request or verified billing. Unsupported or temporarily unavailable capabilities are refused, not silently converted to another API.

Download the versioned public OpenAPI document for machine-readable HTTP request and response schemas. Its info.version identifies the contract release. Unsupported legacy MCP methods are marked as 405 only, not as working transports.

Routes and formats

Method and path	Request	Successful response
`POST /v1/chat/completions`	JSON; text, tools and supported multimodal parts	JSON or SSE with `stream: true`
`POST /v1/messages`	Anthropic-style JSON	Anthropic JSON or SSE events
`POST /v1/responses`	Responses JSON	JSON or Responses SSE events
`POST /v1/responses/compact`	JSON; `model`, optional input or previous response	JSON compaction result
`GET /v1/responses/{response_id}`	Project-owned response ID	Stored response JSON
`GET /v1/models`	Supported discovery filters	Public canonical model list
`POST /v1/embeddings`	JSON	Vectors and input-token usage
`POST /v1/decisions`	JSON with typed questions	Typed answers, in question order
`POST /v1/images/generations`	JSON	Image JSON
`POST /v1/images/edits`	JSON or multipart	Image JSON
`POST /v1/audio/speech`	JSON	Buffered binary audio, not SSE
`POST /v1/audio/transcriptions`	Multipart file or audio URL	JSON transcript, not SRT/VTT/text
`POST /v1/videos`	JSON	Asynchronous job JSON
`GET /v1/videos/{video_id}`	Project-owned job ID	Job status JSON
`GET /v1/videos/{video_id}/content`	Completed project-owned job ID	Video content
`GET /v1/videos/logs/{log_id}/content`	Project-owned log ID	Video content alias
`POST /v1/moderations`	JSON	Categories, scores and flags
`POST /v1/rerank`	JSON	Ranked document indices and scores
`POST /v1/ocr`	JSON	Pages and OCR usage
`POST /v1/search`	JSON	Search results

Model availability

GET /v1/models retains the model inventory, but endpoints contains only interfaces currently allowed by verified capability and billing bounds. declared_endpoints lists the full interface declaration, including interfaces that cannot currently be used. Neither a declaration nor the number of records proves successful calls.

availability summarizes the model as available, unavailable or unverified. Use each api_availability entry's endpoint and status for a particular interface: one available interface does not make every other interface available. unavailable means checked and not currently usable; unverified means not established, not permission to try an unaccounted request. Project and plan entitlements still apply.

Sending JSON

Replace the literal MODEL in JSON bodies with a model listed for that endpoint. For multipart and SDK shell examples, set the MODEL environment variable to that ID. Replace the endpoint and body as needed.

curl "https://api.cloakray.com/v1/embeddings" \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"MODEL","input":["First document","Second document"],"encoding_format":"float"}'

Embeddings

POST /v1/embeddings requires model and input. Input can be a string, a batch of strings, token IDs, or batches of token IDs where the model supports them. encoding_format is float or base64; dimensions is model-dependent. Usage has input/prompt tokens, not a fabricated completion-token count.

{"model":"MODEL","input":["First document","Second document"],"encoding_format":"float","dimensions":1024}

Decisions

POST /v1/decisions requires model, input and one or more questions. Questions have type predicate, choice or score; this is not a chat-messages payload. Choice values retain their string or boolean type. Score levels are ordered lowest first.

{"model":"MODEL","input":"I was charged twice.","questions":[{"type":"predicate","name":"billing","instructions":"Is this about billing?"},{"type":"choice","name":"team","instructions":"Choose the responsible team.","choices":[{"value":"billing"},{"value":"support"}]},{"type":"score","name":"urgency","instructions":"Rate urgency.","levels":[{"label":"low"},{"label":"high"}]}]}

Image edits

POST /v1/images/edits accepts JSON images with image_url entries and a prompt, or a multipart image upload. Multipart accepts image, image[] or file; the reference consumes the first image file, not every repeated field. An optional mask is a file. Supported sizes, counts and output formats depend on the model. See image generation for generation rather than editing.

{"model":"MODEL","images":[{"image_url":"https://example.com/input.png"}],"prompt":"Make the background blue","n":1}

curl "https://api.cloakray.com/v1/images/edits" \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-F "model=$MODEL" -F "image=@input.png" -F "prompt=Make the background blue"

Speech and transcription

POST /v1/audio/speech requires model and input. voice, speed and instructions are model-dependent. Request response_format from wav, pcm, mp3, opus, aac or flac only where that model supports it. Save the response as bytes. There is no customer stream/SSE option in this contract.

curl "https://api.cloakray.com/v1/audio/speech" \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model":"MODEL","input":"Hello there","response_format":"wav"}' \
--output speech.wav

POST /v1/audio/transcriptions is multipart, with model plus file or url. Optional fields are language, diarize, filler_words and repeatable keyterm. Boolean form values are strings such as true. It returns JSON; there is no response_format selector for plain text, SRT or VTT.

curl "https://api.cloakray.com/v1/audio/transcriptions" \
-H "Authorization: Bearer $CLOAKRAY_API_KEY" \
-F "model=$MODEL" -F "file=@meeting.wav" \
-F "diarize=true" -F "keyterm=Project Aurora"

Video jobs

POST /v1/videos creates a job. Model-dependent options include seconds, size, audio and reference media. Use the returned ID for status and content; another project cannot retrieve it. A creation response is not a finished video. Poll with backoff until the job reaches a terminal state, then fetch content only on success. Do not assume repeated status/content reads create another charge.

{"model":"MODEL","prompt":"A paper boat crossing a quiet pond","seconds":8,"size":"1280x720","audio":true}

curl "https://api.cloakray.com/v1/videos/$VIDEO_ID" -H "Authorization: Bearer $CLOAKRAY_API_KEY"
curl "https://api.cloakray.com/v1/videos/$VIDEO_ID/content" -H "Authorization: Bearer $CLOAKRAY_API_KEY" --output video.mp4

The log-content alias is GET /v1/videos/logs/{log_id}/content, with the same project-ownership requirement. There is no standalone GET /v1/videos/logs/{log_id} contract. Do not assume reference callback extensions are available; they require separate ownership and delivery support.

Moderation, reranking, OCR and search

Endpoint	Example JSON body	Notes
`/v1/moderations`	`{"model":"MODEL","input":"Text to check"}`	Input is required; reference model defaults do not bypass available-model checks.
`/v1/rerank`	`{"model":"MODEL","query":"quiet keyboard","documents":["Silent keys","Loud switches"],"top_n":1}`	Requires model, query and documents; `return_documents` and `max_chunks_per_doc` are model-dependent.
`/v1/ocr`	`{"model":"MODEL","document":{"type":"document_url","document_url":"https://example.com/report.pdf"}}`	Requires model and document; page selection and image extraction are optional.
`/v1/search`	`{"model":"MODEL","query":"open source language models","max_results":5}`	Query may be a string or up to five strings; date/domain/language filters depend on support. `people` search is not an enabled reference search type.

Storage, errors and pricing

For Responses, use store: false when you do not want a stored response. Reference storage defaults to a 30-day retention window; do not infer zero retention when requesting stored responses. Retrieval and previous_response_id require the same project. Never assume cancel/delete routes exist merely because an SDK exposes those methods.

JSON errors follow the endpoint's vocabulary; Messages errors use the Anthropic shape. 401 concerns credentials, 402 concerns available credit, 404 concerns an unavailable model/resource, 405 an unsupported method and 429 rate limiting. Accounting or temporary capability failures can refuse a request rather than succeeding without a confirmed charge. Respect Retry-After when provided.

Billing units vary: input/output tokens, characters, audio duration, images, video seconds, OCR pages or requests. A generic token estimate is not a media price. Check model pricing; no gateway fees are added. Token Plans do not automatically include every new modality. See compatibility and product differences for discovery filters, SDK/MCP protocols and privacy.