Import a remote asset

Queue an HTTPS download with a byte limit and return its import job. Choose an explicit URL or an exact JSON pointer into an immutable MCP result payload. A 202 means the job was saved, not that the file is ready. Poll the job until it succeeds and returns an artifact_id.

Idempotency-Key is required and scoped to the caller and organization. Repeating the same request returns the same job; changing its source or metadata with the same key returns 409. The accepted job is retained through a service interruption.

Downloads reject redirects, private-network destinations, embedded credentials, non-HTTPS URLs, and files exceeding the requested byte limit. An expected media type or SHA-256 digest must match before publication. Source URLs are never returned by polling APIs.

The filename's extension decides the format. A response Content-Type must agree with it when it names a specific type. No type, application/octet-stream or binary/octet-stream, and text/plain for a text format (as GitHub raw files and many static hosts serve Markdown, JSON or CSV) leave the decision to the format's content checks.

Supported filename extensions share Knowledge's canonical format registry: .3gpp, .aac, .ac3, .adoc, .aif, .aiff, .asciidoc, .astro, .avi, .bash, .bat, .bmp, .bzl, .c, .cc, .cfg, .cjs, .clj, .cljc, .cljs, .cmake, .cmd, .conf, .cpp, .cs, .css, .csv, .cts, .cxx, .dart, .doc, .dockerfile, .dockerignore, .docx, .editorconfig, .edn, .eex, .eml, .entitlements, .env, .erl, .escript, .eslintrc, .ex, .exs, .fish, .flac, .flv, .fs, .fsx, .gemspec, .geojson, .gif, .gitignore, .go, .gql, .gradle, .graphql, .groovy, .h, .hcl, .heex, .heic, .heif, .hh, .hpp, .hrl, .hs, .htm, .html, .hxx, .ics, .ini, .inl, .intentdefinition, .java, .jl, .jpeg, .jpg, .js, .json, .json5, .jsonc, .jsx, .just, .kt, .kts, .leex, .less, .log, .lua, .m, .m4a, .m4v, .makefile, .markdown, .md, .mdx, .metal, .mjs, .ml, .mm, .modulemap, .mov, .mp3, .mp4, .mpeg, .mpg, .msg, .mts, .nim, .ogg, .ogv, .opus, .org, .pbxproj, .pch, .pdf, .perl, .php, .pl, .plist, .pm, .png, .podspec, .ppt, .pptx, .prettierrc, .properties, .proto, .ps1, .psm1, .py, .pyi, .pyw, .pyx, .r, .rake, .rb, .rs, .rst, .rtf, .s, .sass, .sc, .scala, .scss, .sh, .sol, .sql, .storyboard, .stringsdict, .svelte, .svg, .swift, .swiftinterface, .tcl, .tex, .text, .tf, .tfvars, .tiff, .toml, .ts, .tsconfig, .tsv, .tsx, .txt, .url, .v, .vcard, .vcf, .vue, .wav, .webm, .webp, .wma, .wmv, .xcconfig, .xcscheme, .xcstrings, .xcworkspacedata, .xhtml, .xib, .xls, .xlsx, .xml, .yaml, .yml, .zig, .zsh. Format admission does not enable Knowledge ingestion or previews.

Downloads preserve untrusted bytes without executing scripts, fetching referenced resources, parsing documents, or extracting archives. Source/markup/data text must be UTF-8 without binary controls; its upstream charset must be omitted, utf-8, or utf8. DOCX, PPTX and XLSX receive ZIP metadata checks with strict size and member-count limits, without decompression; encrypted, split, ZIP64 and recognized macro-bearing containers are rejected. Other newly accepted binaries are stored opaquely, not validated as well-formed documents or scanned for malware.

The effective byte cap is the smallest of max_bytes, the shared category cap, and 100 MiB (text: 25 MiB; images: 50 MiB). Newly accepted formats are download-only. Existing PNG, JPEG, GIF, WebP, PDF, MP4, MP3 and WAV imports retain their preview policy. Artifact, binding and approval-file responses expose download_only; when true, both URL endpoints force an attachment with application/octet-stream. HTML is always download-only, including non-imported HTML. Opening a downloaded file is a separate client action.

Imports produce caller-owned, untrusted input artifacts, not run-produced outputs or completion attestations. No tool is invoked or retried, and the source run is not paused or resumed.

JSON pointers address the saved result payload, for example /structured_content/image_url. The selected value must already be a URL string. Text content is not parsed as JSON and URLs are never discovered recursively.

Required access

Credentials: automation account, delegated token, user session, user API key

User API keys use the owner’s current permissions, subject to any key restrictions. Capability scopes below apply to automation account keys and delegated tokens.

Scope: runs:create

Creates a job owned by the calling identity in the active organization. Viewers and resource-allowlisted automation accounts cannot import. An MCP result source additionally requires current permission to read that exact run's results; automation accounts need explicit runs:read_results and can use only their own non-private runs.

Header Parameters

Response Body

curl -X POST "https://example.com/api/v1/artifacts/imports" \  -H "Authorization: Bearer $GUEST_MACHINES_API_KEY" \  -H "Idempotency-Key: 9f8c2b7a-1d3e-4f5a-8b6c-2e1d0a9f8c7b" \  -H "Content-Type: application/json" \  -d '{    "source": {      "kind": "url",      "url": "https://assets.example.com/report.pdf"    },    "file_name": "report.pdf",    "max_bytes": 10485760,    "expected_media_type": "application/pdf"  }'

{  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",  "status": "queued",  "source_kind": "url",  "source_run_id": 0,  "source_result_sequence": 0,  "artifact_id": "b7bd6bbb-c7f1-4314-8742-2aeeeece9d12",  "file_name": "string",  "max_bytes": 0,  "expected_media_type": "string",  "expected_sha256": "string",  "description": "string",  "attempts": 0,  "error_code": "string",  "created_at": "2019-08-24T14:15:22Z",  "updated_at": "2019-08-24T14:15:22Z",  "completed_at": "2019-08-24T14:15:22Z"}