API reference

Uploads

Every media field in the API accepts an upload ID, a public https URL or a base64 data URL. Upload first when a file is large, is reused across requests, or is not publicly reachable.

Uploads are deleted after 7 days. Media attached to a character or product is copied and kept with it.

New files count toward a daily allowance per account, 50 files and 1 GB on Free. https and data URLs passed in media fields are stored as uploads and count too. See Rate limits.

The upload object

idstring
upl_ + 32 hex characters. Use it in any media field.
kindstring
image, video or audio (from the content type).
content_typestring
MIME type.
sizeinteger | null
Bytes; null until a signed upload finishes.
urlstring
Public URL of the stored file. For a signed upload it changes when the upload turns ready, to the checked copy; pass the ID rather than this URL.
statusstring
pending (signed upload not finished) or ready.
created_atinteger
Unix ms.
expires_atinteger
Unix ms, 7 days after creation.
box_idstring
Present when the file was added through an MCP upload box (box_ + 24 hex characters).

Create an upload

POST/v1/uploads

Scope: generateIdempotency-Key requiredReturns 201

Three modes — send exactly one: content_type (returns a signed URL you PUT the file to, for files up to 200 MB), url (Orior downloads a public https file), or data (inline base64 data URL, up to 20 MB).

Body

content_typestring
Signed mode. image/png, image/jpeg, image/webp, image/heic, image/gif, video/mp4, video/quicktime, video/webm, video/x-m4v, audio/mpeg, audio/mp4, audio/aac, audio/wav, audio/ogg, audio/webm.
sizeinteger
Signed mode, optional. Bytes, checked against the limit up front.
urlstring
Import mode. Public https URL (port 443, no credentials, at most 3 redirects).
datastring
Inline mode. data:<mime>;base64,<…>.
box_idstring
Optional, any mode. Groups the file under an MCP upload box so it can be listed later.

Notes

Signed mode: PUT the raw bytes to upload_url with the returned Content-Type within 15 minutes. The upload becomes ready the first time it is used or retrieved: Orior then copies the file, checks it and uses only that copy, so a later PUT to upload_url does not change a ready upload.
Limits: images 20 MB, videos 200 MB, audio 50 MB.

Errors

Code	When
`VALIDATION_ERROR`	Unsupported type, too large, private/unreachable URL, or not a data URL.
`RATE_LIMITED`	The account’s daily upload allowance is used up; `Retry-After` counts to 00:00 UTC.

Request

curl -X POST https://api.oriorai.com/v1/uploads \
  -H "Authorization: Bearer $ORIOR_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "content_type": "video/mp4",
  "size": 48123904
}'

const response = await fetch('https://api.oriorai.com/v1/uploads', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
    'Idempotency-Key': crypto.randomUUID(),
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "content_type": "video/mp4",
    "size": 48123904
  }),
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os, uuid
import requests

response = requests.post(
    "https://api.oriorai.com/v1/uploads",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}", "Idempotency-Key": str(uuid.uuid4())},
    json={
        "content_type": "video/mp4",
        "size": 48123904,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 201

Response

{
  "id": "upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
  "kind": "video",
  "content_type": "video/mp4",
  "size": 48123904,
  "url": "https://storage.googleapis.com/…/api-uploads/…/upl_4f1c….mp4",
  "status": "pending",
  "created_at": 1758620000000,
  "expires_at": 1759224800000,
  "upload_url": "https://storage.googleapis.com/…?X-Goog-Signature=…",
  "upload_method": "PUT",
  "upload_headers": {
    "Content-Type": "video/mp4"
  },
  "upload_expires_at": 1758620900000
}

Retrieve an upload

GET/v1/uploads/{id}

Scope: readReturns 200

Returns the upload; for a signed upload this confirms the file arrived, checks that its content is the declared kind of media (image, video or audio) and marks it ready.

Path parameters

idstringrequired
Upload ID.

Errors

Code	When
`VALIDATION_ERROR`	The file was never uploaded, exceeds the limit, is not the declared kind of media, or the upload expired. A rejected file is deleted; `PUT` the right one while `upload_url` is valid.
`NOT_FOUND`	Unknown ID or another account’s upload.
`RATE_LIMITED`	The file would pass the account’s daily upload bytes; it is deleted.

Request

curl https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60 \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/uploads/upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "id": "upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
  "kind": "video",
  "content_type": "video/mp4",
  "size": 48123904,
  "url": "https://storage.googleapis.com/…",
  "status": "ready",
  "created_at": 1758620000000,
  "expires_at": 1759224800000
}

List an upload box

GET/v1/uploads

Scope: readReturns 200

The files added through one MCP upload box (the open_upload_box tool), oldest first. Expired uploads are left out.

Query parameters

box_idstringrequired
Upload box ID (box_…).

Errors

Code	When
`VALIDATION_ERROR`	Missing or malformed box_id.

Request

curl https://api.oriorai.com/v1/uploads \
  -H "Authorization: Bearer $ORIOR_API_KEY"

const response = await fetch('https://api.oriorai.com/v1/uploads', {
  headers: {
    Authorization: `Bearer ${process.env.ORIOR_API_KEY}`,
  },
})
const data = await response.json()
if (!response.ok) throw new Error(`${data.error.code}: ${data.error.message}`)

import os
import requests

response = requests.get(
    "https://api.oriorai.com/v1/uploads",
    headers={"Authorization": f"Bearer {os.environ['ORIOR_API_KEY']}"},
    timeout=60,
)
response.raise_for_status()
data = response.json()

Response · 200

Response

{
  "object": "list",
  "data": [
    {
      "id": "upl_4f1c9e0a7b2d4c6e8f0a1b2c3d4e5f60",
      "kind": "image",
      "content_type": "image/jpeg",
      "size": 2481920,
      "url": "https://storage.googleapis.com/…",
      "status": "ready",
      "created_at": 1758620000000,
      "expires_at": 1759224800000,
      "box_id": "box_9b0c1d2e3f4a5b6c7d8e9f0a"
    }
  ]
}