{
  "openapi": "3.1.0",
  "info": {
    "title": "83blue transfer API",
    "version": "1.0.0",
    "summary": "Free, no-signup file transfer for AI agents and humans",
    "description": "Upload a file, get a share url and a password, hand both to any other agent or person; they download with one request. No accounts, no API keys, no cookies. Automated and bot use is welcome. Files up to 1 TB (chunked) or 512 MB in a single request, deleted automatically after 1-180 days (default 180; MCP tool calls default to 30). A remote MCP server (Streamable HTTP, no auth) with tools send_text, send_files and receive runs at https://upload.83blue.com/mcp. A2A agent card: https://upload.83blue.com/.well-known/agent-card.json (endpoint /a2a).",
    "x-mcp-server": "https://upload.83blue.com/mcp",
    "x-llms-txt": "https://upload.83blue.com/llms.txt",
    "x-a2a-agent-card": "https://upload.83blue.com/.well-known/agent-card.json"
  },
  "externalDocs": {
    "description": "Human-readable docs",
    "url": "https://upload.83blue.com/docs"
  },
  "servers": [
    {
      "url": "https://upload.83blue.com"
    }
  ],
  "paths": {
    "/api/upload": {
      "post": {
        "operationId": "uploadFile",
        "summary": "One-shot upload (up to 512 MB)",
        "description": "Multipart body with a `file` field, or a raw body (also via PUT) with the file name in `?name=` or an `X-Filename` header. Returns the share url, the password and a ready-made download command.",
        "parameters": [
          {
            "name": "name",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "File name for raw-body uploads"
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 8,
              "maxLength": 64
            },
            "description": "Custom password; a strong one is generated when omitted"
          },
          {
            "name": "expires_days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 180,
              "default": 180
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": {
                    "type": "string",
                    "format": "binary"
                  },
                  "password": {
                    "type": "string"
                  },
                  "expires_days": {
                    "type": "integer"
                  }
                }
              }
            },
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Uploaded",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transfer"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "description": "Too large for a single request; use the chunked protocol. Bodies over ~520 MB are rejected by the web server itself with a plain non-JSON 413.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "507": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/download": {
      "get": {
        "operationId": "downloadFile",
        "summary": "Download a transfer (supports HTTP Range)",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "20-char transfer id, or the full share url"
          },
          {
            "name": "password",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/info": {
      "get": {
        "operationId": "transferInfo",
        "summary": "Transfer metadata without downloading",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "20-char transfer id, or the full share url"
          },
          {
            "name": "password",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transfer"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/create": {
      "post": {
        "operationId": "createChunkedUpload",
        "summary": "Start a chunked, resumable upload (files up to 1 TB)",
        "description": "Re-creating with the same fingerprint and size from the same IP resumes the unfinished transfer (offset > 0). A fresh password is issued either way.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "size",
                  "fingerprint"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "size": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 1099511627776
                  },
                  "fingerprint": {
                    "type": "string",
                    "pattern": "^[a-f0-9]{64}$",
                    "description": "Any 64-char hex id for the file, e.g. sha256 of name|size"
                  },
                  "password": {
                    "type": "string",
                    "minLength": 8,
                    "maxLength": 64
                  },
                  "expires_days": {
                    "type": "integer",
                    "minimum": 1,
                    "maximum": 180
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Created or resumed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "token": {
                      "type": "string"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "resumed": {
                      "type": "boolean"
                    },
                    "password": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "507": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/chunk": {
      "post": {
        "operationId": "appendChunk",
        "summary": "Append raw bytes to a chunked upload (chunks up to 256 MB)",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "offset",
            "in": "query",
            "required": true,
            "schema": {
              "type": "integer"
            },
            "description": "Must equal the bytes already stored; on mismatch the reply is 409 with the real offset"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/octet-stream": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Appended (complete=true with the share link when finished)",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "complete": {
                      "type": "boolean"
                    },
                    "link": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "Offset mismatch; body contains the real offset",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          },
          "413": {
            "description": "Chunk larger than 256 MB. Bodies over ~520 MB are rejected by the web server itself with a plain non-JSON 413.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorBody"
                }
              }
            }
          }
        }
      }
    },
    "/api/status": {
      "get": {
        "operationId": "uploadStatus",
        "summary": "Current offset of a chunked upload (for resuming)",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "complete": {
                      "type": "boolean"
                    },
                    "offset": {
                      "type": "integer"
                    },
                    "link": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/f/{token}/{key}": {
      "parameters": [
        {
          "name": "token",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "capabilityDownload",
        "summary": "Download via capability url (no password; supports HTTP Range)",
        "responses": {
          "200": {
            "description": "The file",
            "content": {
              "application/octet-stream": {
                "schema": {
                  "type": "string",
                  "format": "binary"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "delete": {
        "operationId": "capabilityDelete",
        "summary": "Delete the transfer via its capability url",
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/h/{token}/{key}": {
      "parameters": [
        {
          "name": "token",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "key",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "operationId": "handoffBriefing",
        "summary": "Agent handoff briefing: markdown (or JSON via Accept) explaining the transfer, its manifest and how to fetch it",
        "responses": {
          "200": {
            "description": "Briefing",
            "content": {
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              },
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transfer"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/delete": {
      "delete": {
        "operationId": "deleteTransfer",
        "summary": "Delete a transfer (token + password, or a capability url in token)",
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "password",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Deleted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "deleted": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Transfer": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean"
          },
          "token": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "description": "Human share page; give this plus the password to the recipient"
          },
          "filename": {
            "type": "string"
          },
          "size": {
            "type": "integer"
          },
          "size_human": {
            "type": "string"
          },
          "expires_at": {
            "type": "string",
            "format": "date-time"
          },
          "downloads": {
            "type": "integer"
          },
          "password": {
            "type": "string"
          },
          "download": {
            "type": "object",
            "properties": {
              "api": {
                "type": "string",
                "description": "Direct download url including the password"
              },
              "curl": {
                "type": "string",
                "description": "Ready-made download command"
              }
            }
          },
          "handoff": {
            "type": "string",
            "description": "Plain-English instructions to pass to the recipient"
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 of the stored file (recorded for files up to 1 GB)"
          },
          "capability_url": {
            "type": "string",
            "description": "GET downloads the raw file, DELETE removes the transfer; the whole secret is in the url"
          },
          "handoff_url": {
            "type": "string",
            "description": "Fetching returns a markdown briefing + manifest any model understands; the one url to paste into any chat"
          },
          "service": {
            "type": "object",
            "description": "Reusable pointer to this service (mcp endpoint, agent card, docs)"
          }
        }
      },
      "ErrorBody": {
        "type": "object",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "string"
          },
          "offset": {
            "type": "integer",
            "description": "Present on 409 chunk offset mismatches"
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "Error",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ErrorBody"
            }
          }
        }
      }
    }
  }
}