> ## Documentation Index > Fetch the complete documentation index at: https://docs.trybloom.ai/llms.txt > Use this file to discover all available pages before exploring further. # Upload files > Reserve private, temporary storage for local files in your workspace and receive upload instructions. PUT each raw file using the returned upload URL, method, and required headers to stage its bytes, then pass its `uploadId` to a supported operation before it expires. For new Brand source evidence, pass the ID to [POST /brands](/api-reference/brands/create-a-brand). To add an image to a Brand Library, pass it to [POST /images/uploads](/api-reference/images/add-an-image-to-a-brand-library). Staging alone creates no Brand source, Library image, font asset, or logo. See [Upload local files](/guides/upload-files) for the full workflow and additional MCP destinations. ## OpenAPI ````yaml https://www.trybloom.ai/api/v1/spec.json post /uploads openapi: 3.1.1 info: title: Bloom API version: 1.0.0 servers: - url: https://www.trybloom.ai/api/v1 security: - apiKey: [] - bearer: [] tags: - name: Account description: >- Inspect the authenticated account — profile, credit balance, and accessible workspaces. - name: Brands description: Manage brands and brand identity. - name: Images description: Generate, edit, and retrieve images. - name: Uploads description: >- Stage private local files for Brand sources, Library images, and other supported operations. paths: /uploads: post: tags: - Uploads summary: Upload files description: >- Reserve private, temporary storage for local files in your workspace and receive upload instructions. PUT each raw file using the returned upload URL, method, and required headers to stage its bytes, then pass its `uploadId` to a supported operation before it expires. For new Brand source evidence, pass the ID to [POST /brands](/api-reference/brands/create-a-brand). To add an image to a Brand Library, pass it to [POST /images/uploads](/api-reference/images/add-an-image-to-a-brand-library). Staging alone creates no Brand source, Library image, font asset, or logo. See [Upload local files](/guides/upload-files) for the full workflow and additional MCP destinations. operationId: uploads.create requestBody: required: true content: application/json: schema: type: object properties: workspaceId: type: string minLength: 1 description: Team workspace ID. Omit for the personal workspace. files: type: array minItems: 1 maxItems: 30 items: type: object properties: filename: type: string minLength: 1 maxLength: 240 description: Original filename used when the upload is consumed byteLength: type: integer minimum: -9007199254740991 maximum: 104857600 exclusiveMinimum: 0 description: Exact file size in bytes required: - filename - byteLength additionalProperties: false description: >- Local files to stage (1–30, at most 100 MiB each and 256 MiB combined) required: - files additionalProperties: false responses: '201': description: OK content: application/json: schema: type: object properties: data: type: object properties: uploads: type: array items: type: object properties: uploadId: type: string format: uuid filename: type: string byteLength: type: integer minimum: -9007199254740991 maximum: 9007199254740991 exclusiveMinimum: 0 uploadUrl: type: string format: uri method: const: PUT headers: type: object properties: content-type: const: application/octet-stream cache-control: const: max-age=3600 x-upsert: const: 'false' required: - content-type - cache-control - x-upsert expiresAt: type: string format: date-time x-native-type: date required: - uploadId - filename - byteLength - uploadUrl - method - headers - expiresAt required: - uploads required: - data '400': description: '400' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate400ErrorResponse' '401': description: '401' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate401ErrorResponse' '403': description: '403' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate403ErrorResponse' '404': description: '404' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate404ErrorResponse' '429': description: '429' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate429ErrorResponse' headers: Retry-After: description: >- Seconds until the API-key request limit resets. Present only when the request-rate limiter can calculate the delay. schema: type: integer minimum: 0 '500': description: '500' content: application/json: schema: $ref: '#/components/schemas/UploadsCreate500ErrorResponse' components: schemas: UploadsCreate400ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: INVALID_UPLOAD status: const: 400 message: type: string default: Invalid upload request data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error UploadsCreate401ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: UNAUTHORIZED status: const: 401 message: type: string default: Invalid or missing API credentials data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error UploadsCreate403ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: ACCOUNT_BANNED status: const: 403 message: type: string default: This account has been suspended. data: {} required: - code - status - message - type: object properties: code: const: FORBIDDEN status: const: 403 message: type: string default: Plan upgrade required data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error UploadsCreate404ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: WORKSPACE_NOT_FOUND status: const: 404 message: type: string default: Workspace not found or not accessible data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error UploadsCreate429ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: TOO_MANY_REQUESTS status: const: 429 message: type: string default: Rate limit exceeded data: {} required: - code - status - message - type: object properties: code: const: UPLOAD_QUOTA_EXCEEDED status: const: 429 message: type: string default: Temporary upload limit reached data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error UploadsCreate500ErrorResponse: type: object properties: error: allOf: - $ref: '#/components/schemas/ApiError' - anyOf: - type: object properties: code: const: INTERNAL_ERROR status: const: 500 message: type: string default: Failed to create uploads data: {} required: - code - status - message - type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message required: - error ApiError: type: object properties: code: type: string status: type: integer message: type: string data: {} required: - code - status - message securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: 'Bloom API key, for example `x-api-key: bloom_sk_...`.' bearer: type: http scheme: bearer description: Bloom API key (`Bearer bloom_sk_...`) or Bloom OAuth access token. ````