# Create upload

Create a private PNG/JPEG/WebP upload (1–10485760 bytes). Finalize within 15 minutes; signed PUT capability lasts 2 hours and cannot overwrite. No remote URL ingestion.

Endpoint: POST /v1/uploads
Version: 1.0.0
Security: bearerAuth

## Security:

  - `bearerAuth` (unknown)
    http bearer

## Header parameters:

  - `Idempotency-Key` (string, required)
    Reuse for an uncertain retry of the same intent.

## Request fields (application/json):

  - `media_type` (string, required)
    Enum: "image/png", "image/jpeg", "image/webp"

  - `size` (integer, required)

## Response 200:

  - `200` (unknown)
    Terminal operation job.

## Response 200 fields (application/json):

  - `job` (object, required)

  - `job.id` (string, required)

  - `job.command` (string, required)

  - `job.resourceId` (string, required)

  - `job.state` (string, required)
    Enum: "queued", "running", "waiting_for_approval", "succeeded", "partially_failed", "failed", "cancelling", "cancelled", "recovery_required"

  - `job.createdAt` (string, required)

  - `job.updatedAt` (string, required)

  - `job.result` (any, required)

  - `job.result.resourceId` (string)

  - `job.result.revision` (string)

  - `job.result.insertedTotal` (integer)

  - `job.result.updatedTotal` (integer)

  - `job.result.deletedTotal` (integer)

  - `job.result.items` (array)

  - `job.result.items.index` (integer, required)

  - `job.result.items.id` (string)

  - `job.result.items.status` (string, required)
    Enum: "inserted", "updated", "unchanged", "deleted", "invalid_request", "duplicate_external_id", "recipient_locked", "resource_not_found"

  - `job.result.succeeded` (number)

  - `job.result.failed` (number)

  - `job.result.secretAvailable` (boolean)
    Enum: "false"

  - `job.pollAfterSeconds` (number, required)

  - `upload` (object, required)

  - `upload.id` (string, required)

  - `upload.status` (string, required)
    Enum: "pending", "ready", "revoked", "expired"

  - `upload.media_type` (string, required)
    Enum: "image/png", "image/jpeg", "image/webp"

  - `upload.size` (integer, required)

  - `upload.finalize_before` (string, required)

  - `upload.upload_capability_validity_seconds` (number, required)
    Enum: "7200"

  - `upload.revision` (string, required)

  - `capability` (any, required)

  - `capability.url` (string, required)

  - `capability.method` (string, required)
    Enum: "PUT"

  - `capability.content_type` (string, required)

  - `capability.issued_at` (string, required)

  - `capability.validity_seconds` (number, required)
    Enum: "7200"

## Response 200 headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.

  - `Location` (string, required)
    Absolute URL of the operation job, from the trusted server origin.

  - `ETag` (string)
    Quoted opaque revision when the resource or job result has one.

## Response 202:

  - `202` (unknown)
    Nonterminal operation job; poll Location after Retry-After seconds.

## Response 202 fields (application/json):

  - `job` (object, required)

  - `job.id` (string, required)

  - `job.command` (string, required)

  - `job.resourceId` (string, required)

  - `job.state` (string, required)
    Enum: "queued", "running", "waiting_for_approval", "succeeded", "partially_failed", "failed", "cancelling", "cancelled", "recovery_required"

  - `job.createdAt` (string, required)

  - `job.updatedAt` (string, required)

  - `job.result` (any, required)

  - `job.result.resourceId` (string)

  - `job.result.revision` (string)

  - `job.result.insertedTotal` (integer)

  - `job.result.updatedTotal` (integer)

  - `job.result.deletedTotal` (integer)

  - `job.result.items` (array)

  - `job.result.items.index` (integer, required)

  - `job.result.items.id` (string)

  - `job.result.items.status` (string, required)
    Enum: "inserted", "updated", "unchanged", "deleted", "invalid_request", "duplicate_external_id", "recipient_locked", "resource_not_found"

  - `job.result.succeeded` (number)

  - `job.result.failed` (number)

  - `job.result.secretAvailable` (boolean)
    Enum: "false"

  - `job.pollAfterSeconds` (number, required)

  - `upload` (object, required)

  - `upload.id` (string, required)

  - `upload.status` (string, required)
    Enum: "pending", "ready", "revoked", "expired"

  - `upload.media_type` (string, required)
    Enum: "image/png", "image/jpeg", "image/webp"

  - `upload.size` (integer, required)

  - `upload.finalize_before` (string, required)

  - `upload.upload_capability_validity_seconds` (number, required)
    Enum: "7200"

  - `upload.revision` (string, required)

  - `capability` (any, required)

  - `capability.url` (string, required)

  - `capability.method` (string, required)
    Enum: "PUT"

  - `capability.content_type` (string, required)

  - `capability.issued_at` (string, required)

  - `capability.validity_seconds` (number, required)
    Enum: "7200"

## Response 202 headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.

  - `Location` (string, required)
    Absolute URL of the operation job, from the trusted server origin.

  - `Retry-After` (integer, required)
    Seconds to wait before polling or retrying.

  - `ETag` (string)
    Quoted opaque revision when the resource or job result has one.

## Response 401:

  - `401` (unknown)
    Missing or invalid Bearer authentication.

## Response 401 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Enum: "activation_prerequisites_missing", "asset_storage_unavailable", "batch_limit_exceeded", "catalog_unavailable", "idempotency_conflict", "insufficient_scope", "invalid_asset", "invalid_request", "method_not_allowed", "not_found", "operation_conflict", "operation_failed", "origin_forbidden", "payload_too_large", "precondition_failed", "precondition_required", "rate_limited", "render_source_unavailable", "tenant_disabled", "transaction_retry_required", "unauthorized", "unsupported_media_type", "upload_expired", "upload_incomplete", "upload_revoked"

  - `error.requestId` (string, required)

## Response 401 headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.

  - `WWW-Authenticate` (string, required)
    Enum: "Bearer"

## Response 405:

  - `405` (unknown)
    Method not allowed for this path.

## Response 405 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Enum: "activation_prerequisites_missing", "asset_storage_unavailable", "batch_limit_exceeded", "catalog_unavailable", "idempotency_conflict", "insufficient_scope", "invalid_asset", "invalid_request", "method_not_allowed", "not_found", "operation_conflict", "operation_failed", "origin_forbidden", "payload_too_large", "precondition_failed", "precondition_required", "rate_limited", "render_source_unavailable", "tenant_disabled", "transaction_retry_required", "unauthorized", "unsupported_media_type", "upload_expired", "upload_incomplete", "upload_revoked"

  - `error.requestId` (string, required)

## Response 405 headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.

  - `Allow` (string, required)
    Comma-separated methods allowed for this path.

## Response 429:

  - `429` (unknown)
    Rate limited; wait before retrying.

## Response 429 fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Enum: "activation_prerequisites_missing", "asset_storage_unavailable", "batch_limit_exceeded", "catalog_unavailable", "idempotency_conflict", "insufficient_scope", "invalid_asset", "invalid_request", "method_not_allowed", "not_found", "operation_conflict", "operation_failed", "origin_forbidden", "payload_too_large", "precondition_failed", "precondition_required", "rate_limited", "render_source_unavailable", "tenant_disabled", "transaction_retry_required", "unauthorized", "unsupported_media_type", "upload_expired", "upload_incomplete", "upload_revoked"

  - `error.requestId` (string, required)

## Response 429 headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.

  - `Retry-After` (integer, required)
    Seconds to wait before polling or retrying.

## Response default:

  - `default` (unknown)
    Error. The JSON body contains error.code and error.requestId.

## Response default fields (application/json):

  - `error` (object, required)

  - `error.code` (string, required)
    Enum: "activation_prerequisites_missing", "asset_storage_unavailable", "batch_limit_exceeded", "catalog_unavailable", "idempotency_conflict", "insufficient_scope", "invalid_asset", "invalid_request", "method_not_allowed", "not_found", "operation_conflict", "operation_failed", "origin_forbidden", "payload_too_large", "precondition_failed", "precondition_required", "rate_limited", "render_source_unavailable", "tenant_disabled", "transaction_retry_required", "unauthorized", "unsupported_media_type", "upload_expired", "upload_incomplete", "upload_revoked"

  - `error.requestId` (string, required)

## Response default headers (application/json):

  - `X-Request-Id` (string, required)
    Identifier for tracing this response.