# Upload files (https://docs.capy.ai/api-reference/files/upload-files)

`POST https://api.capy.ai/api/v1/files`

## Authorization

Send an API key as a bearer token: `Authorization: Bearer $CAPY_API_KEY`. See https://docs.capy.ai/api-reference/authentication.md.

## Request body

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `files` | object[] | yes | The files to upload, at least one and at most 250 MB each. The answer's `targets` come back in this order. |

## Responses

- `200` FileUploadTargets: `FileUploadTargetsEncoded`
- `401` capy/Unauthorized: `capy_UnauthorizedEncoded`
- `403` capy/Forbidden: `capy_ForbiddenEncoded`
- `429` capy/RateLimited: `capy_RateLimitedEncoded`

## Example

```bash
curl -X POST "https://api.capy.ai/api/v1/files" \
  -H "Authorization: Bearer $CAPY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"files":[]}'
```

## Referenced schemas

```json
{
  "FileUploadTargetsEncoded": {
    "type": "object",
    "properties": {
      "targets": {
        "type": "array",
        "items": {
          "$ref": "#/components/schemas/FileUploadTargetEncoded"
        }
      }
    },
    "required": [
      "targets"
    ],
    "additionalProperties": false
  },
  "FileUploadTargetEncoded": {
    "type": "object",
    "properties": {
      "fileId": {
        "type": "string",
        "description": "The upload's id. Attach it to a message by passing it in the send's `files`."
      },
      "url": {
        "type": "string",
        "description": "A presigned URL. PUT the file's bytes to it with exactly the declared `Content-Type` and `Content-Length`, and no Authorization header."
      },
      "expiresAt": {
        "type": "string"
      }
    },
    "required": [
      "fileId",
      "url",
      "expiresAt"
    ],
    "additionalProperties": false
  },
  "capy_UnauthorizedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Unauthorized"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_ForbiddenEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/Forbidden"
        ]
      }
    },
    "required": [
      "_tag"
    ],
    "additionalProperties": false
  },
  "capy_RateLimitedEncoded": {
    "type": "object",
    "properties": {
      "_tag": {
        "type": "string",
        "enum": [
          "capy/RateLimited"
        ]
      },
      "retryAfterSeconds": {
        "type": "integer"
      }
    },
    "required": [
      "_tag",
      "retryAfterSeconds"
    ],
    "additionalProperties": false
  },
  "UploadFilesRequest": {
    "type": "object",
    "properties": {
      "files": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "maxLength": 1024,
              "description": "The file name shown on the attachment."
            },
            "mediaType": {
              "type": "string",
              "description": "The file's media type, such as `image/png` or `video/mp4`, 1-255 printable ASCII characters. The PUT must send it as `Content-Type`."
            },
            "sizeBytes": {
              "type": "integer",
              "minimum": 1,
              "maximum": 262144000,
              "description": "The file's exact size in bytes. The PUT must send it as `Content-Length`."
            }
          },
          "required": [
            "name",
            "mediaType",
            "sizeBytes"
          ],
          "additionalProperties": false
        },
        "description": "The files to upload, at least one and at most 250 MB each. The answer's `targets` come back in this order."
      }
    },
    "required": [
      "files"
    ],
    "additionalProperties": false
  }
}
```

Full document: https://docs.capy.ai/openapi.json