К содержанию
TelegaFirst

Для AI-агентов: markdown этой страницы — /docs/api-op-requestsiteupload.mdиндекс документации — /llms.txt

requestSiteUpload

Обновлено

POST /api/v1/tools/site/request-upload

Request staged bundle upload URLs

Авторизация и права

Scopes: ALL. Auth alternatives: OR; scopes внутри альтернативы: ALL.

ПолеЗначение
security.0.hubApiKey[]
security.1.hubBearer[]
securitySchemes.hubApiKey.in"header"
securitySchemes.hubApiKey.name"X-Api-Key"
securitySchemes.hubApiKey.type"apiKey"
securitySchemes.hubBearer.scheme"bearer"
securitySchemes.hubBearer.type"http"
x-required-scopes["site:write"]

Параметры запроса

ПолеЗначение
0.description"Tenant, credential and handler-bound byte-shape replay key"
0.in"header"
0.name"Idempotency-Key"
0.requiredtrue
0.schema0.schema

Тело запроса

ПолеЗначение
content.application/json.schemaSiteUploadRequest
requiredtrue

Ответы

ПолеЗначение
201.content.application/json.schemaSiteUploadTicket
201.description"Tenant site control-plane result"
201.headers.X-Bot-Username.description"Active bot username, when resolved"
201.headers.X-Bot-Username.schema201.headers.X-Bot-Username.schema
201.headers.X-Client-Slug.description"Active tenant slug, when resolved"
201.headers.X-Client-Slug.schema201.headers.X-Client-Slug.schema
201.headers.X-RateLimit-Limit.description"Effective request budget"
201.headers.X-RateLimit-Limit.schema201.headers.X-RateLimit-Limit.schema
201.headers.X-RateLimit-Remaining.description"Remaining request budget"
201.headers.X-RateLimit-Remaining.schema201.headers.X-RateLimit-Remaining.schema
201.headers.X-RateLimit-Reset.description"Unix window reset in seconds"
201.headers.X-RateLimit-Reset.schema201.headers.X-RateLimit-Reset.schema

Ошибки

ПолеЗначение
400.content.application/problem+json.schemaProblemDetails
400.description"Invalid strict upload declaration or missing replay key"
400.x-error-codes["VALIDATION_ERROR","IDEMPOTENCY_KEY_REQUIRED"]
401.content.application/problem+json.schemaProblemDetails
401.description"Missing, invalid, revoked or conflicting credential; surface JWT is refused"
401.x-error-codes["INVALID_API_KEY"]
403.content.application/problem+json.schemaProblemDetails
403.description"Missing scope, prohibited publishable credential or absent active bot"
403.x-error-codes["INSUFFICIENT_SCOPE","PUBLISHABLE_KEY_NOT_ALLOWED","NO_ACTIVE_BOT"]
404.content.application/problem+json.schemaProblemDetails
404.description"Host is not a live tenant UGC or verified custom domain"
404.x-error-codes["NOT_FOUND"]
409.content.application/problem+json.schemaProblemDetails
409.description"Typed domain conflict or request in flight"
409.x-error-codes["CONFLICT"]
413.content.application/problem+json.schemaProblemDetails
413.description"Resource policy size or item-count limit exceeded"
413.x-error-codes["PAYLOAD_TOO_LARGE","ITEM_COUNT_EXCEEDED"]
422.content.application/problem+json.schemaProblemDetails
422.description"Replay mismatch; a path outside the permitted publication prefix or reserved on a tenant site host; a video over the per-video size of the plan (details.path, details.limitBytes); a bundle over the site size of the plan (details.limitBytes) or over the file count of a site, the same on every plan (details.limitFiles)"
422.x-error-codes["IDEMPOTENCY_KEY_MISMATCH","SITE_PATH_OUTSIDE_PUBLISHABLE_PREFIX","SITE_PATH_RESERVED","SITE_VIDEO_TOO_LARGE","SITE_BUNDLE_TOO_LARGE","SITE_TOO_MANY_FILES"]
429.content.application/problem+json.schemaProblemDetails
429.description"Resource rate budget exceeded or unavailable, or the daily upload budget of the plan is spent: tickets, one per request whatever its file count (details.limitTickets, details.remainingTickets), and declared bytes (details.limitBytes, details.remainingBytes); details.retryAfter is the reset at UTC midnight. With remainingTickets 0 only that reset helps; with tickets left, a declaration within remainingBytes is issued today"
429.headers.Retry-After.description"Retry delay in seconds, when supplied by the limiter"
429.headers.Retry-After.schema429.headers.Retry-After.schema
429.x-error-codes["RATE_LIMIT_EXCEEDED","RATE_LIMIT_UNAVAILABLE","MINT_QUOTA_EXCEEDED"]
500.content.application/problem+json.schemaProblemDetails
500.description"Unexpected internal failure"
500.x-error-codes["INTERNAL_ERROR"]
503.content.application/problem+json.schemaProblemDetails
503.description"The daily upload budget could not be checked; no ticket was issued. Repeat after Retry-After"
503.headers.Retry-After.description"Retry delay in seconds, when supplied by the limiter"
503.headers.Retry-After.schema503.headers.Retry-After.schema
503.x-error-codes["MINT_QUOTA_UNAVAILABLE"]

Дополнительные условия

ПолеЗначение
description"Owner-only site:write. Canonical UGC host ({slug}.{ugc zone} in either zone) or connected verified custom host; tenant UGC on the main platform host is prohibited. Nonempty declared files; each includes path, integer nonnegative sizeBytes, contentType and optional references. mode defaults to merge: omitted bio, binary assets, gates and references are preserved. Explicit replace declares a complete snapshot and removes omitted files and rules. The issuer pins canonical host, mode and server-owned baseManifestDigest; caller base/client fields are forbidden. The facade checks tenant host, safe paths, dependencies, each video file against the per-video size of the plan (by the served type of its extension, before the bundle total), the full effective site quota and the daily upload budget before minting. Video files (.mp4, .webm) are accepted within that size. Every refusal names its limit in details. Signed PUTs target staging and bind Content-Length. Expire in 300 seconds. No secret approval gate."
operationId"requestSiteUpload"
summary"Request staged bundle upload URLs"
tags["site"]
x-idempotency.conflictStatus422
x-idempotency.implementation"global-cache"
x-idempotency.replayStatus201
x-idempotency.requiredtrue
x-idempotency.scope["client","credential","controller-handler","key"]
x-idempotency.ttlSeconds86400
x-pagination.queryParameters[]
x-pagination.supportedfalse
x-scope-semantics"ALL"