Start an upload

post/v1/advertisement-uploads

This endpoint is in the contract, but the API doesn't serve it during early access. It returns 404 for now.

Step 1 of 2. Reserves storage and returns a presigned PUT URL with Content-Length and Content-Type signed in, so the PUT must match the declared size_bytes and content_type. The object key is chosen by the server. Over 2 GB returns 413; over the org's storage quota returns 402 storage_quota_exceeded. Then POST /v1/advertisements with the upload_id.

curl -X POST "https://api.vojo-media.com/v1/advertisement-uploads" \
  -H "Authorization: Bearer $VOJO_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "file_name": "acme-summer-15s.mp4",
  "content_type": "video/mp4",
  "size_bytes": 18874368
}'

const { data, error } = await api.POST("/v1/advertisement-uploads", {
  params: { header: { "Idempotency-Key": crypto.randomUUID() } },
  body: {
    file_name: "acme-summer-15s.mp4",
    content_type: "video/mp4",
    size_bytes: 18874368,
  },
});
if (error) throw new VojoApiError(error);

Response 201

{
  "data": {
    "upload_id": "cm1sto8p2o0001i4u7y3t6r9un",
    "url": "https://vojo.lon1.digitaloceanspaces.com/cm1org8k2q0001x7v3n9p4d2fa/9b1e.mp4?X-Amz-Expires=900&X-Amz-Signature=8e1d7b3c",
    "method": "PUT",
    "headers": {
      "Content-Type": "video/mp4",
      "Content-Length": "18874368"
    },
    "expires_at": "2026-10-07T09:45:00Z"
  },
  "meta": {}
}

Access

Authentication: Secret key or OAuth access token.
Scope: advertisements:write
User permission: advertisementAddNew
Safe to retry: Send an Idempotency-Key.

Headers

Vojo-Organisationstring
The organisation this request acts on (org id). Required for oauth2 callers — a missing header returns 400 organisation_header_required; an org the user cannot access (a membership or an access grant, and granted to this OAuth client) returns 403 organisation_access_denied. Secret keys are bound to one org: the header may be omitted, and if sent it must match the key's org (else 403). Every query is scoped by the resolved org, never by an id in the body.
Vojo-Versionstring
Optional API version pin (a date). Overrides the version pinned on the secret key / organisation for this request. Echoed in the Vojo-Version response header. Within /v1 only additive changes ship, so most callers can omit it.
date
Idempotency-Keystring
Client-generated unique key (UUID v4 recommended) making this create safe to retry. A replay within 24 hours returns the stored response (with Idempotent-Replayed: true). Reusing a key with a different body returns 409 idempotency_key_reused.
8 to 255 characters

Request body

file_namestringRequired
1 to 255 characters
content_typestringRequired
MIME type, e.g. video/mp4. Signed into the URL.
3 to 127 characters
size_bytesintegerRequired
Exact byte size. Signed into the URL as Content-Length.
1 to 2147483648

Response 201

Created

dataobjectRequired
A pending upload slot. PUT the file to url, then register it with POST /v1/advertisements.
Show 5 fields
- upload_idstringRequired
  Upload id. Opaque string — treat as an identifier, never parse it.
- urlstringRequired
  Presigned upload URL. Content-Length and Content-Type are signed in.
  uri
- methodstringRequired
  One of PUT
- headersmap of stringRequired
  HTTP headers the PUT must send exactly (header names are HTTP header names, not wire fields).
- expires_atstringRequired
  URL expiry.
  date-time
metaobjectRequired
Response metadata for single-resource responses. Reserved; currently empty. Clients must ignore unknown members.

Response headers

Vojo-Versionstring
The API version (date) this response was rendered with — the request's Vojo-Version, else the key/org pin.
RateLimitstring
IETF RateLimit header: remaining quota in the current window, e.g. "default";r=97;t=42.
RateLimit-Policystring
IETF RateLimit-Policy header, e.g. "default";q=100;w=60. Portal OAuth clients get a higher tier.
Idempotent-Replayedstring
true when this response is a stored replay of an earlier request with the same Idempotency-Key.

Errors

Every error is application/problem+json. Branch on its code.

400
Malformed request: invalid JSON, a bad cursor, a missing Vojo-Organisation for an OAuth caller, or an unknown Vojo-Version.
401
Missing, invalid, expired or revoked credential.
402
An entitlement or quota blocks this request. feature_key, limit and used explain which.
403
The caller is authenticated but not allowed: missing scope (insufficient_scope), missing Permissions flag (permission_denied), a client/installer persona on an operator endpoint (operator_access_required), or no access to the requested org (organisation_access_denied).
413
The declared upload exceeds the per-object maximum (2 GB).
422
Well-formed request that failed validation. errors[] lists each failing field.
429
Rate limit exceeded for this principal. Back off for Retry-After seconds.
500
Unexpected server failure.