aethexDocs
Dashboard

API Reference

Uploads API

Mint short-lived presigned URLs for uploading large files directly to storage. Skip this endpoint for small payloads; the relevant resource APIs all accept inline multipart/form-data up to their own size caps.When to use. When you need to upload a file that exceeds the inline cap on its consuming endpoint:- Knowledge-base documents larger than ~10 MiB (use kind doc/knowledge-base, then call POST /agents/{id}/knowledge-base/by-upload).
- Audio files for transcription that exceed the inline cap (use kind audio/transcribe, then call POST /transcribe/by-upload or POST /transcribe/async/by-upload). Both inline and presigned paths share the same 8 MiB ASR backend cap.
- Recordings for a voice clone (use kind audio/voice-clone, WAV only, at most 25 MiB, then call POST /voices/clone/by-upload).How it works. This endpoint mints a presigned PUT URL targeted at storage. Your client PUTs the file bytes directly to that URL (no Aethex auth on the storage URL). You then call the resource endpoint with the returned upload_id. The upload_id is single-use and expires after 1 hour.Scope rule. Presigning a kind requires the same scope you would need to consume it. For example, kind: "doc/knowledge-base" requires agents:write. This prevents you from presigning an upload you would not be allowed to use.

Base URL
https://api.aethexai.com/api/v1
Endpoints
1
POST/uploads/presign

Mint a single-use presigned PUT URL for large files. Expires in 1 hour.

Presign an Upload

Mints a presigned PUT URL for the given upload kind. Returns the URL, an upload_id to pass to the consuming endpoint, and the expected Content-Type to use on the PUT.The upload_id is an opaque signed token (JWT) — treat it as a bearer string. Do not pattern-match on prefix or length; the format may change. Pass it back verbatim to the consuming endpoint.The upload_id is single-use; once consumed by a resource endpoint, it cannot be reused. Unused IDs expire after 1 hour.

Request body

4
  • kindstringrequired

    Upload kind. One of: doc/knowledge-base (knowledge-base file for an agent), audio/transcribe (audio file for transcription), audio/voice-clone (WAV recording for a voice clone).

  • content_typestringrequired

    MIME type your client will send on the PUT. The presigned URL is bound to this type; if you PUT a different content-type, storage will reject.

  • filenamestringoptional

    Original filename. Carried through to the consuming endpoint so the resource record keeps a meaningful name. Optional but recommended.

  • size_hintintegeroptional

    Expected file size in bytes. Must be between 0 and 1073741824 (1 GiB) inclusive. The server currently validates the range but does not echo the value back in the response; treat it as a forward-compatible hint.

Errors

3
401Unauthorized

Missing or invalid API key.

Send X-API-Key: '<'api_key'>'.

403Missing scope for upload kind

The API key does not carry the scope required by the chosen kind. For example, doc/knowledge-base requires agents:write; audio/transcribe requires transcribe:use; audio/voice-clone requires voices:write.

Issue a new key with the scope the upload kind requires, then retry.

422Invalid kind

kind is missing or not one of the supported values (doc/knowledge-base, audio/transcribe, audio/voice-clone).

Send one of the supported kind values.