bird assets uploads

Usage

bird assets uploads

Description

Sessions freeze a file's exact size and SHA-256 and return temporary PUT instructions. Completion publishes the transferred file. Retries use the same session ID. File bytes travel through the HTTP upload, outside tool arguments.

Reads return JSON. Mutations take flags and/or a --body-file JSON body (flags overriding); run --example to print the body shape or --dry-run to preview the request.

Procedure

Upload a file to the media library

Create an upload session, transfer the original bytes in code, then complete publication.

Requires: Use the execution environment to read the original file and calculate its exact size and SHA-256. Completing this flow publishes the file at a permanent public URL. If file access is unavailable, explain that limitation and stop; do not put file bytes in tool arguments.

1. bird assets uploads create — Supply a new client_reference, the exact file descriptor and the requested asset metadata. Retain the session ID and original input. For retries, keep the same workspace and OAuth connection or API key that created the session. Token refresh retains access; reconnecting or changing keys creates a new owner. Check state and the returned next steps first. If pending has no upload, wait 30 seconds, then retry the original create request unchanged. A completed replay already has its result; do not transfer again. When upload is present, the code environment needs outbound HTTPS PUT access to the hostname in upload.url. A working MCP connection does not establish that access. If network policy blocks the host, ask an organization administrator to allow that exact hostname in the code environment's network settings. Share the hostname without the path, query, or required_headers; do not request access to all S3 hosts. New signed URLs for the same hostname use the same allowlist entry; another region may use another host. DNS failures and timeouts alone do not prove an allowlist block. If transfer is blocked, explain the network prerequisite and stop before completion. When upload is present and the host is reachable, PUT the original bytes in code using upload.method, upload.url, upload.required_headers and upload.content_length. Send no Bird authorization headers or cookies. Keep the signed URL and required_headers out of chat and logs, and file bytes outside model context. After network access is restored, retry the original create request unchanged with the same workspace and OAuth connection or API key to recover a still-valid session. Follow its returned state; an expired session needs a new upload intent. Replaying with a different owner can create a separate session instead of recovering the original. Next: bird assets uploads complete
2. bird assets uploads complete — After the PUT succeeds, complete the same session. Confirm state is completed and use its result; retries must keep the same session ID.

Commands