POST /v1/uploads
Create a single-use, environment-scoped upload for an ImportBundle of at most 16 MiB. Send exactly size_bytes bytes to upload_url using upload_method and every value in upload_headers, then create the import with bundle_upload_id before expires_at. The signer supplies the required headers; Content-Type is not promised to be signed. The import validates and freezes the uploaded bytes before consuming the upload, so later object changes cannot change a queued import.
- Scope
imports:write- Auth
- Secret key (
sk_…) - Since
- 1.0
Headers
Section titled “Headers”
Minor version; defaults to the environment’s pin.OhAuthCat-Versionstring
Honoured for 24 h; a replay returns the original response.Idempotency-Keystringmin length 1 · max length 255
Request body
Section titled “Request body”purposestring Requiredone of
import_bundle,csv_saml,auth0_users,auth0_mapping
Exact uploaded byte length. ImportBundle and CSV ZIP uploads are limited to 16 MiB. Auth0 JSON lines exports are limited to 64 MiB and streamed; Auth0 organization CSV mappings are limited to 5 MiB.size_bytesinteger Requiredmin 1
Responses
Section titled “Responses”- 201 OK Upload
- 400 Invalid request. Codes: parameter_invalid, parameter_missing, version_unsupported and resource-specific codes from the catalogue. Error
- 401 Codes: authentication_required, api_key_invalid. Error
- 403 Codes: api_key_scope_missing, ip_not_allowed, plan_limit_reached. Error
- 409 Codes: idempotency_key_reused and resource-specific conflicts. Error
- 429 Code: rate_limited. Retry-After is set. Error
- 503 Code: service_unavailable. Retry-After is set; writes are paused. Error
- default Any other error, including internal_error. Every code is in the error catalogue. Error
Errors share one shape; see the error code catalogue.
curl -X POST \ "https://api.ohauthcat.com/v1/uploads" \ -H "Authorization: Bearer $OHAUTHCAT_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "purpose": "import_bundle", "size_bytes": 1}'const response = await fetch("https://api.ohauthcat.com/v1/uploads", { method: "POST", headers: { Authorization: `Bearer ${process.env.OHAUTHCAT_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "purpose": "import_bundle", "size_bytes": 1 }),});const data = await response.json();import osimport requests
response = requests.post( "https://api.ohauthcat.com/v1/uploads", headers={"Authorization": f"Bearer {os.environ['OHAUTHCAT_API_KEY']}"}, json={ "purpose": "import_bundle", "size_bytes": 1, },)data = response.json(){ "id": "upl_01J9Z3K5V7W8X9Y0Z1A2B3C4D5", "object": "upload", "upload_url": "https://app.acme.com/callback", "upload_method": "PUT", "upload_headers": {}, "expires_at": "2026-01-15T09:30:00Z"}