{
  "openapi": "3.1.0",
  "info": {
    "title": "FileGrab Agent API",
    "version": "1.0.0",
    "description": "Create links and upload one exact local file through a mailbox-authorized FileGrab agent connection."
  },
  "servers": [
    {
      "url": "https://api.filegrab.link"
    }
  ],
  "tags": [
    {
      "name": "Access",
      "description": "Mailbox confirmation and authorization"
    },
    {
      "name": "Links"
    },
    {
      "name": "Uploads"
    },
    {
      "name": "Files"
    }
  ],
  "paths": {
    "/api/v1/health": {
      "get": {
        "summary": "Check API health",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Access"
        ]
      }
    },
    "/api/v1/agent-registrations": {
      "post": {
        "summary": "Request agent signup confirmation",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Access"
        ]
      }
    },
    "/api/v1/agent-activation-verifications": {
      "post": {
        "summary": "Confirm an activation token",
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Access"
        ]
      }
    },
    "/api/v1/agent-authorizations": {
      "post": {
        "summary": "Renew 7-day mailbox authorization",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Access"
        ]
      }
    },
    "/api/v1/account": {
      "get": {
        "summary": "Read the connected account and allowance",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Access"
        ]
      }
    },
    "/api/v1/links": {
      "get": {
        "summary": "List owned links",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Links"
        ]
      },
      "post": {
        "summary": "Create a link",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Links"
        ]
      }
    },
    "/api/v1/links/{linkId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/LinkId"
        }
      ],
      "get": {
        "summary": "Read a link and its files",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Links"
        ]
      },
      "patch": {
        "summary": "Update a link",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Links"
        ]
      },
      "delete": {
        "summary": "Delete a link",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Links"
        ]
      }
    },
    "/api/v1/links/{linkId}/uploads": {
      "parameters": [
        {
          "$ref": "#/components/parameters/LinkId"
        }
      ],
      "post": {
        "summary": "Initialize a direct upload",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Uploads"
        ]
      }
    },
    "/api/v1/uploads/{uploadId}/parts/url": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "post": {
        "summary": "Sign one multipart part",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Uploads"
        ]
      }
    },
    "/api/v1/uploads/{uploadId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "get": {
        "summary": "Read upload status",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Uploads"
        ]
      }
    },
    "/api/v1/uploads/{uploadId}/complete": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "post": {
        "summary": "Complete an upload",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Uploads"
        ]
      }
    },
    "/api/v1/uploads/{uploadId}/abort": {
      "parameters": [
        {
          "$ref": "#/components/parameters/UploadId"
        }
      ],
      "post": {
        "summary": "Abort an upload",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Uploads"
        ]
      }
    },
    "/api/v1/files/{fileId}": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "get": {
        "summary": "Read file metadata",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Files"
        ]
      },
      "delete": {
        "summary": "Delete a file",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/files/{fileId}/download": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "get": {
        "summary": "Download a completed file",
        "security": [
          {
            "agentKey": []
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Files"
        ]
      }
    },
    "/api/v1/files/{fileId}/short-url": {
      "parameters": [
        {
          "$ref": "#/components/parameters/FileId"
        }
      ],
      "post": {
        "summary": "Create or recover the short URL",
        "security": [
          {
            "agentKey": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        },
        "tags": [
          "Files"
        ]
      }
    }
  },
  "components": {
    "securitySchemes": {
      "agentKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "fg_agent_"
      }
    },
    "parameters": {
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": true,
        "schema": {
          "type": "string",
          "maxLength": 255
        }
      },
      "LinkId": {
        "name": "linkId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "UploadId": {
        "name": "uploadId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string"
        }
      },
      "FileId": {
        "name": "fileId",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request is invalid"
      },
      "Unauthorized": {
        "description": "The API key or 7-day mailbox authorization is invalid or expired"
      },
      "RateLimited": {
        "description": "The request limit was reached"
      }
    }
  }
}