Resource paths
Provider reads use resource paths such as/v1/videos/{id}?provider=youtube. Every provider read requires exactly one provider query parameter; resource IDs stay in the path. Missing providers return PROVIDER_REQUIRED, and unsupported values return PROVIDER_NOT_SUPPORTED.
Provider IDs must match exactly, including case, with no surrounding whitespace.
Project search uses /v1/projects/{projectId}/search?q=... and only searches that project’s indexed material. The authenticated user must own the project. API keys and CLI sessions require both data:read and account:access permissions. The project ID belongs in the path, not the query or request body.
Provider identity in monitor and import request bodies remains part of the saved resource definition.
Credits
Metered responses include:
A request that fails with
402 returns X-Credits-Charged: 0. Each operation holds a reserve before it runs, so a 402 can happen when your balance would cover the final charge. See credits for per-operation prices and reserves.
Pagination
Search, browse, comments, channel catalogs, and playlists return opaque continuation values. Pass the value back to the same endpoint and do not parse, modify, or reuse it with another query.Source metadata
Normalized responses identify their provider, extractor, fetch time, partial state, and warnings. Optional upstream fields may be absent. A partial response can still contain usable data; inspect warnings before treating it as complete.Errors
Errors use a stable envelope with a machine-readable code and human-readable message. Common statuses include401 for missing authentication, 402 for insufficient credits, 422 for invalid input, 429 for rate limiting, and 503 for a temporarily unavailable provider.
Only retry operations identified as retryable. Preserve idempotency keys for job-creating requests.