API v1 preview

Create a file

POST/api/v1/files

Overview

Create a file record and receive temporary upload instructions. Upload the bytes to the returned URL using the supplied form fields. Registration does not upload or validate the model. Idempotency-Key is optional; successful retries return the original snapshot for 24 hours.

Requires files:write.

Upload guide: transfer and retention Errors and retries

Request

cURL

curl -X POST "$API_BASE_URL/api/v1/files" \
  -H "Authorization: Bearer $OTTOMFG_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "filename": "figurine.zip",
  "size_bytes": 10485760
}'

Use your configured API_BASE_URL and the signed upload fields returned by your request.

More request examples

Request body

{
  "filename": "figurine.zip",
  "size_bytes": 10485760
}

Complete upload examples

// Node.js 22+. Set API_BASE_URL and OTTOMFG_API_KEY on your server.
import { randomUUID } from "node:crypto";
import { openAsBlob } from "node:fs";
import { stat } from "node:fs/promises";
import { basename } from "node:path";

const file = "figurine.zip";
const base = process.env.API_BASE_URL.replace(/\/$/, "");
// Generate once per intended registration; persist and reuse on retries.
const idempotencyKey = randomUUID();
const response = await fetch(`${base}/api/v1/files`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OTTOMFG_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": idempotencyKey,
  },
  body: JSON.stringify({ filename: basename(file), size_bytes: (await stat(file)).size }),
  signal: AbortSignal.timeout(30_000),
});
if (!response.ok) {
  console.error(`Registration failed (${response.status}):`, await response.text());
  process.exit(1); // Inspect code/message; do not blindly retry registration.
}
const registration = await response.json();
const form = new FormData();
for (const [name, value] of Object.entries(registration.upload.fields)) {
  form.append(name, value);
}
form.append("file", await openAsBlob(file), basename(file)); // File must be last.
const transfer = await fetch(registration.upload.url, {
  method: registration.upload.method,
  body: form, // No API key or manual Content-Type header on the storage request.
  signal: AbortSignal.timeout(3_600_000),
});
if (!transfer.ok) throw new Error(`Storage upload failed (${transfer.status})`);
console.log(registration.id);

Node.js 22+; cURL requires Bash, curl 7.76+, jq and uuidgen; Python requires requests (python -m pip install requests). File bytes are sent last, without your API key.

Parameters

Idempotency-Key header · optional

Account, method and path scoped retry key, retained for 24 hours from first use. Same body replays the original successful status and body. A changed body returns 409 idempotency_key_reused; an in-flight request returns 409 idempotency_request_in_progress with Retry-After. Retry transient failures with the same key and body.

string

Request body

application/json

filename string · required

Original filename, including .glb, .obj, or .zip. Maximum 255 characters; directory paths, leading/trailing whitespace, and control characters are not allowed.

Min length: 1 · Max length: 255

size_bytes integer (int64) · required

Exact file size in bytes. For ZIPs, use the compressed size. Maximum 400000000 bytes (400 MB).

Minimum: 1 · Maximum: 400000000

Responses

HTTP status

File registered; upload the bytes using the returned instructions.

200 response

JSON

{
  "upload": {
    "method": "POST",
    "url": "https://example-upload-bucket.s3.amazonaws.com/",
    "fields": {
      "key": "files/2a08c3d391244972a31a0f87d3821fa9/source",
      "policy": "GENERATED_POLICY",
      "x-amz-algorithm": "AWS4-HMAC-SHA256",
      "x-amz-credential": "GENERATED_CREDENTIAL_SCOPE",
      "x-amz-date": "20260921T180000Z",
      "x-amz-signature": "GENERATED_SIGNATURE",
      "x-amz-security-token": "GENERATED_SESSION_TOKEN",
      "success_action_status": "204"
    },
    "expires_at": "2026-09-21T19:00:00Z"
  },
  "id": "file_6c82bd3e319b4bb099310d54a761879e"
}

Returns the File object.

Response headers

X-Request-ID

Request identifier for support. Send X-Request-ID with 8–64 ASCII letters, digits or hyphens to reuse that value; otherwise the server generates a UUID4 hex value. Include the returned X-Request-ID in support requests. Do not put secrets or account IDs in this value.

Idempotent-Replayed

Present when the original successful response is replayed.

Errors

HTTP	Code	What to do
400 Bad Request	`file_too_large`	The file is over the upload limit. Reduce it before you register it.
400 Bad Request	`filename_required`	The file registration has no filename. Send the original filename with its extension.
400 Bad Request	`invalid_argument`	A field, query parameter or header is invalid. Fix the field named in details, then send the request again.
400 Bad Request	`invalid_file_size`	size_bytes is not a positive whole number. Send the file's exact byte count.
400 Bad Request	`size_bytes_required`	The file registration has no size_bytes. Send the file's exact byte count.
400 Bad Request	`unsupported_file_extension`	The file type is not supported. Use a GLB, OBJ or ZIP file.
401 Unauthorized	`unauthenticated`	The API key is missing, invalid or revoked. Send a valid business API key in Authorization: Bearer.
403 Forbidden	`permission_denied`	The key lacks the endpoint's scope, or payments lack spending consent. Check the scope listed on the endpoint.
409 Conflict	`idempotency_key_reused`	This Idempotency-Key was already used with a different body. Retry the original body, or use a new key for a new operation.
409 Conflict	`idempotency_request_in_progress`	A request with this Idempotency-Key is still running. Wait Retry-After seconds, then retry the same key and body.
413 Content Too Large	`request_too_large`	The JSON body is over this endpoint's size limit. Send a smaller body.
415 Unsupported Media Type	`unsupported_media_type`	The body is not JSON. Send Content-Type: application/json.
429 Too Many Requests	`resource_exhausted`	A rate or account limit was reached. Wait at least Retry-After seconds, then retry.
500 Internal Server Error	`internal`	The server failed unexpectedly. Retry with backoff; contact support with X-Request-ID if it persists.
503 Service Unavailable	`unavailable`	A required service is briefly unavailable. Retry with backoff, reusing the same Idempotency-Key.

Idempotent requests

API v1 preview