# Cloud API reference

Authentication, request structure, and explicit failure handling.

## Translation endpoint [#translation-endpoint]

`POST /api/platform/v1/translate`

Make server-side requests using a Bearer API key. The project must have a valid cloud-service license, and the platform must have a real inference upstream configured.

```bash
curl "$ELEJO_API_URL/api/platform/v1/translate" \
  -H "Authorization: Bearer $ELEJO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello","source":"en","target":"fr"}'
```

## Parameters [#parameters]

| Field  | Type   | Constraint                                                       |
| ------ | ------ | ---------------------------------------------------------------- |
| text   | string | 1–5000 characters after trimming leading and trailing whitespace |
| source | string | A 2–3-letter lowercase language code                             |
| target | string | A 2–3-letter lowercase language code                             |

A successful response includes a `translation` string. Actual language coverage is determined by the upstream service. The current gateway accepts up to 30 requests per key per minute; this limit is separate from enterprise quotas and billing.

## Errors and retries [#errors-and-retries]

400: invalid input; 401: invalid key; 403: access not enabled or license invalid; 429: too many requests; 502: upstream error; 503: service not configured; 504: upstream timeout. Use backoff with random jitter, retry temporary errors only, and avoid unlimited retries.

## Key lifecycle [#key-lifecycle]

A key's plaintext is shown only once. The platform stores its hash and prefix. To rotate a key, create a replacement, update your server configuration and verify it, then revoke the old key. Do not embed long-lived keys in browsers, mobile app packages, or public repositories.

[Download the OpenAPI contract](/openapi.json)
