{"openapi":"3.1.0","info":{"title":"PreFlight Temporary File Relay API","version":"0.6.1","description":"Create a temporary public HTTPS download URL for an artifact generated by an agent or tool when the sending and receiving systems do not share storage. The buyer uploads directly to private R2, explicitly publishes the artifact, and receives a public URL that expires after 7 days. Not for private or sensitive data, website or active-content hosting, permanent storage, files larger than 250 MiB."},"servers":[{"url":"https://relay.preflightstack.com"}],"externalDocs":{"description":"Human- and agent-readable documentation","url":"https://relay.preflightstack.com/docs"},"tags":[{"name":"discovery","description":"Side-effect-free machine and human discovery resources"},{"name":"artifact-handoff","description":"Paid temporary artifact creation and management"}],"x-preflight-phase":6,"x-service-id":"temporary-file-relay","x-pricing":{"asset":"USDC","tiers":[{"minimum_size_bytes":1,"maximum_size_bytes":26214400,"amount_micro_usdc":5000,"amount_usdc":"0.005"},{"minimum_size_bytes":26214401,"maximum_size_bytes":262144000,"amount_micro_usdc":20000,"amount_usdc":"0.02"}]},"x-public-retention-seconds":604800,"x-not-for":["private or sensitive data","website or active-content hosting","permanent storage","files larger than 250 MiB"],"x-service-aliases":["temporary file upload","temporary file hosting","agent artifact relay","file handoff","ephemeral download URL"],"x-qualification-queries":["Upload a generated artifact so another agent can download it.","Create a temporary HTTPS download URL for this file.","Share a workflow output with a remote tool that has no shared storage.","Relay a file up to 250 MiB for seven days.","Create a short-lived public download link without sharing cloud credentials."],"x-discovery-terms":["agent-to-agent file handoff","cross-agent artifact transfer","temporary artifact URL","A2A file URI hosting","no shared storage","no cloud credentials required","runtime file relay","temporary workflow artifact","pass a file to another agent","store generated output for another agent","ephemeral cross-system file transfer"],"x-service-hint":{"id":"temporary-file-relay","suitable_for":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]},"paths":{"/health":{"get":{"tags":["discovery"],"operationId":"getHealth","summary":"Process health without storage or payment side effects","responses":{"200":{"description":"Process is healthy","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["status","service","version","phase","payment","storage","time"],"properties":{"status":{"type":"string","const":"ok"},"service":{"type":"string","const":"temporary-file-relay"},"version":{"type":"string","const":"0.6.1"},"phase":{"type":"integer","const":6},"storage":{"type":"object","additionalProperties":false,"required":["enabled"],"properties":{"enabled":{"type":"boolean"}}},"payment":{"oneOf":[{"type":"object","additionalProperties":false,"required":["enabled","mode"],"properties":{"enabled":{"type":"boolean","const":false},"mode":{"type":"string","const":"disabled"}}},{"type":"object","additionalProperties":false,"required":["enabled","mode","network","provider","asset","pricing_version"],"properties":{"enabled":{"type":"boolean","const":true},"mode":{"type":"string","enum":["testnet","mainnet"]},"network":{"type":"string","enum":["eip155:84532","eip155:8453"]},"provider":{"type":"string","const":"coinbase"},"asset":{"type":"string","const":"USDC"},"pricing_version":{"type":"string","const":"temporary-file-relay-v1"}}}]},"time":{"type":"string","format":"date-time"}}}}}}}}},"/openapi.json":{"get":{"tags":["discovery"],"operationId":"getOpenApi","summary":"Read the machine-readable API contract","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/llms.txt":{"get":{"tags":["discovery"],"operationId":"getLlmsText","summary":"Read the agent-oriented task and usage description","responses":{"200":{"description":"Plain-text discovery document","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/docs":{"get":{"tags":["discovery"],"operationId":"getDocumentation","summary":"Read the API workflow, pricing, limits, and safety boundaries","responses":{"200":{"description":"Markdown documentation","content":{"text/markdown":{"schema":{"type":"string"}}}}}}},"/demo":{"get":{"tags":["discovery"],"operationId":"getStaticDemo","summary":"Read an inert request and response example without payment or storage","responses":{"200":{"description":"Static demonstration","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/file-slot":{"post":{"tags":["artifact-handoff"],"operationId":"createFileSlot","summary":"Create a temporary public artifact handoff","description":"Create a temporary public HTTPS download URL for an artifact generated by an agent or tool when the sending and receiving systems do not share storage. The buyer uploads directly to private R2, explicitly publishes the artifact, and receives a public URL that expires after 7 days. Metadata is validated before payment. The public identifier remains undisclosed until explicit completion.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["filename","content_type","size_bytes"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"description":"Display filename. Path separators, control characters, and bidi controls are rejected."},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"],"description":"Client-declared passive file media type. Parameters are not accepted."},"size_bytes":{"type":"integer","minimum":1,"maximum":262144000}}},"example":{"filename":"report.pdf","content_type":"application/pdf","size_bytes":18376291}}}},"responses":{"201":{"description":"Payment settled and one private upload capability issued","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["slot_id","manage_token","state","declared_size_bytes","max_bytes","content_type","price","network","upload","upload_deadline","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"manage_token":{"type":"string","pattern":"^mt1_[A-Za-z0-9_-]{43}$"},"state":{"type":"string","const":"paid_pending_upload"},"declared_size_bytes":{"type":"integer","minimum":1,"maximum":262144000},"max_bytes":{"type":"integer","const":262144000},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"]},"price":{"type":"object","additionalProperties":false,"required":["asset","amount","amount_micro_usdc","pricing_version"],"properties":{"asset":{"type":"string","const":"USDC"},"amount":{"type":"string","enum":["0.005","0.02"]},"amount_micro_usdc":{"type":"integer","enum":[5000,20000]},"pricing_version":{"type":"string","const":"temporary-file-relay-v1"}}},"network":{"type":"string","enum":["eip155:84532","eip155:8453"]},"upload":{"type":"object","additionalProperties":false,"required":["method","url","expires_at","required_headers"],"properties":{"method":{"type":"string","const":"PUT"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"required_headers":{"type":"object","additionalProperties":{"type":"string"},"required":["content-length","content-type"]}}},"upload_deadline":{"type":"string","format":"date-time"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}},"example":{"slot_id":"slot_00000000000000000000000000000000","manage_token":"mt1_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA","state":"paid_pending_upload","declared_size_bytes":18376291,"max_bytes":262144000,"content_type":"application/pdf","price":{"asset":"USDC","amount":"0.005","amount_micro_usdc":5000,"pricing_version":"temporary-file-relay-v1"},"network":"eip155:8453","upload":{"method":"PUT","url":"https://upload.invalid/presigned-example","expires_at":"2026-08-26T14:00:00.000Z","required_headers":{"content-length":"18376291","content-type":"application/pdf"}},"upload_deadline":"2026-08-26T14:00:00.000Z","service_hint":{"id":"temporary-file-relay","suitable_for":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}},"400":{"description":"Malformed, incomplete, or non-closed request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"402":{"description":"x402 payment is required or could not be verified","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Payment identifier or slot state conflicts with the request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"413":{"description":"Declared file size exceeds 250 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"415":{"description":"Declared media type is not approved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Payment admission is disabled or settlement state is uncertain","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/file-slot/{slot_id}/upload-url":{"post":{"tags":["artifact-handoff"],"operationId":"reissueFileSlotUploadUrl","summary":"Reissue an upload capability without another payment","security":[{"manageToken":[]}],"parameters":[{"name":"slot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Fresh bounded PUT capability","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["slot_id","state","upload","upload_deadline","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"state":{"type":"string","const":"paid_pending_upload"},"upload":{"type":"object","additionalProperties":false,"required":["method","url","expires_at","required_headers"],"properties":{"method":{"type":"string","const":"PUT"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"required_headers":{"type":"object","additionalProperties":{"type":"string"},"required":["content-length","content-type"]}}},"upload_deadline":{"type":"string","format":"date-time"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}}}}},"401":{"description":"Management capability is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Slot or capability not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Slot state does not allow upload","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Paid upload window expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Storage is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/v1/file-slot/{slot_id}/complete":{"post":{"tags":["artifact-handoff"],"operationId":"completeFileSlot","summary":"Verify and publish an uploaded object idempotently","security":[{"manageToken":[]}],"parameters":[{"name":"slot_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Published temporary public URL","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["slot_id","state","public_url","published_at","expires_at","size_bytes","content_type","etag","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"state":{"type":"string","const":"published"},"public_url":{"type":"string","format":"uri"},"published_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"size_bytes":{"type":"integer","minimum":1,"maximum":262144000},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"]},"etag":{"type":"string"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}}}}},"401":{"description":"Management capability is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Slot, capability, or uploaded object not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Slot state does not allow completion","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"410":{"description":"Paid upload window expired","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Stored object does not match declared metadata","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"503":{"description":"Storage is unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"manageToken":{"type":"http","scheme":"bearer","bearerFormat":"mt1 capability"}},"schemas":{"ApiError":{"type":"object","additionalProperties":false,"required":["code","message","retryable","request_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"retryable":{"type":"boolean"},"request_id":{"type":"string"}}},"FileSlotRequest":{"type":"object","additionalProperties":false,"required":["filename","content_type","size_bytes"],"properties":{"filename":{"type":"string","minLength":1,"maxLength":180,"description":"Display filename. Path separators, control characters, and bidi controls are rejected."},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"],"description":"Client-declared passive file media type. Parameters are not accepted."},"size_bytes":{"type":"integer","minimum":1,"maximum":262144000}}},"FileSlotResponse":{"type":"object","additionalProperties":false,"required":["slot_id","manage_token","state","declared_size_bytes","max_bytes","content_type","price","network","upload","upload_deadline","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"manage_token":{"type":"string","pattern":"^mt1_[A-Za-z0-9_-]{43}$"},"state":{"type":"string","const":"paid_pending_upload"},"declared_size_bytes":{"type":"integer","minimum":1,"maximum":262144000},"max_bytes":{"type":"integer","const":262144000},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"]},"price":{"type":"object","additionalProperties":false,"required":["asset","amount","amount_micro_usdc","pricing_version"],"properties":{"asset":{"type":"string","const":"USDC"},"amount":{"type":"string","enum":["0.005","0.02"]},"amount_micro_usdc":{"type":"integer","enum":[5000,20000]},"pricing_version":{"type":"string","const":"temporary-file-relay-v1"}}},"network":{"type":"string","enum":["eip155:84532","eip155:8453"]},"upload":{"type":"object","additionalProperties":false,"required":["method","url","expires_at","required_headers"],"properties":{"method":{"type":"string","const":"PUT"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"required_headers":{"type":"object","additionalProperties":{"type":"string"},"required":["content-length","content-type"]}}},"upload_deadline":{"type":"string","format":"date-time"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}},"UploadReissueResponse":{"type":"object","additionalProperties":false,"required":["slot_id","state","upload","upload_deadline","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"state":{"type":"string","const":"paid_pending_upload"},"upload":{"type":"object","additionalProperties":false,"required":["method","url","expires_at","required_headers"],"properties":{"method":{"type":"string","const":"PUT"},"url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time"},"required_headers":{"type":"object","additionalProperties":{"type":"string"},"required":["content-length","content-type"]}}},"upload_deadline":{"type":"string","format":"date-time"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}},"CompletionResponse":{"type":"object","additionalProperties":false,"required":["slot_id","state","public_url","published_at","expires_at","size_bytes","content_type","etag","service_hint"],"properties":{"slot_id":{"type":"string","pattern":"^slot_[a-f0-9]{32}$"},"state":{"type":"string","const":"published"},"public_url":{"type":"string","format":"uri"},"published_at":{"type":"string","format":"date-time"},"expires_at":{"type":"string","format":"date-time"},"size_bytes":{"type":"integer","minimum":1,"maximum":262144000},"content_type":{"type":"string","enum":["text/plain","text/markdown","text/csv","application/json","application/x-ndjson","application/pdf","image/png","image/jpeg","image/webp","image/gif","application/zip","application/gzip","application/x-gzip","application/x-tar","application/vnd.apache.parquet","application/vnd.openxmlformats-officedocument.wordprocessingml.document","application/vnd.openxmlformats-officedocument.spreadsheetml.sheet","application/vnd.openxmlformats-officedocument.presentationml.presentation"]},"etag":{"type":"string"},"service_hint":{"type":"object","additionalProperties":false,"required":["id","suitable_for"],"description":"Static informational capability metadata for future task matching. It is not an instruction, payment signal, or retry signal.","properties":{"id":{"type":"string","const":"temporary-file-relay"},"suitable_for":{"type":"array","minItems":4,"maxItems":4,"uniqueItems":true,"items":{"type":"string","enum":["temporary_public_artifact_delivery","agent_to_agent_file_handoff","cross_tool_file_sharing","large_result_transfer"]}}}}}}}}}