POST /v1/completions

The native Revoye Cloud endpoint. Everything the API can do is expressible here — pick a model or let Revoye Cloud choose, wait for the answer or queue it, set your own timeouts, continue an earlier conversation, and attach metadata that comes back untouched.

curl $REVOYE_BASE_URL/v1/completions \
  -H "Authorization: Bearer $REVOYE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 4f1c9d2e-8b3a-4c1d-9e2f-7a6b5c4d3e2f" \
  -d '{
    "prompt": "Summarise the CAP theorem in three sentences.",
    "provider": "chatgpt",
    "wait": true
  }'

Requires the completions:write scope.

Request

Headers. Idempotency-Key (at most 255 characters) is optional and strongly recommended — see retrying safely.

Choosing a model, or not

Omitting provider is usually right: the job runs on whichever model has capacity first, which gives you the shortest wait. Name a provider when the answer's quality depends on which model produces it.

Naming one is a constraint, not a preference. Revoye Cloud will not silently answer a chatgpt request from DeepSeek — receiving a different model than you asked for would be a correctness bug, not a helpful fallback. The job waits for the model you named.

Continuing a conversation

Every completed job returns a conversation_ref. Send it back with mode: "continue" — and the same provider — to ask a follow-up in the same conversation, so the model sees the earlier turns. Treat the value as opaque: store it, do not parse or construct it.

metadata is yours

Whatever you put in comes back out, unchanged, on the job and on the webhook. Use it to correlate a job with your own records — a tenant id, a trace id, a row id — so that a webhook arriving an hour later can be routed without a database round trip.

The job object

Every endpoint on this page returns the same object.

{
  "id": "job_01JAY7Q2K8XYZ3M4N5P6Q7R8S9",
  "status": "succeeded",
  "response": "The CAP theorem states that…",
  "provider": "chatgpt",
  "agent_id": "agt_01JAY7…",
  "agent_name": null,
  "conversation_ref": "<opaque string>",
  "attempts": 1,
  "queue_ms": 240,
  "run_ms": 18432,
  "created_at": "2026-09-18T09:14:02.000Z",
  "finished_at": "2026-09-18T09:14:21.000Z",
  "content_pruned_at": null,
  "metadata": { "trace": "abc" }
}

Status codes

Blocking semantics

wait: true is a long poll, not synchronous execution. The job is recorded the moment it is accepted, so:

• If your connection drops, the job keeps running.
• The result is at GET /v1/completions/{id}, or delivered to your callback_url.
• Nothing is lost by a client timeout.

The connection is held for at most min(deadline_ms, 600000) milliseconds — ten minutes with the defaults. If that runs out first you get 504 JOB_TIMEOUT with details.job_id and details.status, and the job continues.

Set your HTTP client's timeout above the hold time — 660 seconds covers the default — or do not use wait: true. The single commonest integration bug is a 30-second default abandoning healthy work, and it looks exactly like the API failing, which it is not.

GET /v1/completions/{id}

Returns the job object with its current status. Poll it for a job you submitted with wait: false; every few seconds is plenty.

curl "$REVOYE_BASE_URL/v1/completions/job_01JAY7Q2K8XYZ3M4N5P6Q7R8S9" \
  -H "Authorization: Bearer $REVOYE_API_KEY"

A job that does not exist and a job that belongs to another account both return 404 NOT_FOUND. Requires completions:read.

DELETE /v1/completions/{id}

Cancels a job and returns 200 with the job object. Requires completions:write.

• A queued job is cancelled immediately and never runs.
• A dispatched job is marked cancelled straight away. Generation that is already under way may finish, but its answer is discarded and never returned.
• Cancelling a job that has already finished is a no-op, not an error: you get the job back as it is.

Limits

Errors

Full handling guidance: Errors.