---
updatedAt: 2025-12-05T14:02:27.000Z
agentTools:
  projectIndex: https://docs.staxpayments.com/llms.txt
---

# Add a File 

Uploads a file to the system to be used in invoices or catalog items.

This guide outlines the process for uploading media assets (files/images) to create or update items in the Catalog or Invoice API.
A successful response from this endpoint will provide a unique File ID required to link the asset to a specific item.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "stax-api",
    "version": "0.1"
  },
  "servers": [
    {
      "url": "https://apiprod.fattlabs.com/"
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "API key for merchant-level operations. Provides access to merchant-specific endpoints including transactions, payments, customer management, and merchant account settings. This key is scoped to a single merchant account and cannot access partner-level functionality."
      }
    }
  },
  "security": [
    {
      "ApiKeyAuth": []
    }
  ],
  "paths": {
    "/file": {
      "post": {
        "description": "",
        "operationId": "post_file",
        "responses": {
          "200": {
            "description": "",
            "content": {
              "application/json": {
                "examples": {
                  "OK": {
                    "summary": "OK",
                    "value": {
                      "merchant_id": "55394e80-826a-4e04-bafa-2e2d615209cf",
                      "user_id": "0dcb6380-962a-4b9d-b318-81e5625d0316",
                      "name": "Test Energy Drink Image",
                      "tag": "generic",
                      "id": "497da262-d9b3-4d24-920f-25c9c27522b4",
                      "updated_at": "2025-11-20 20:46:05",
                      "created_at": "2025-11-20 20:46:05",
                      "public_url": "https://fattpaydocuments.s3.us-west-2.amazonaws.com/generic/497da262-d9b3-4d24-920f-25c9c27522b4.jpg",
                      "meta": {
                        "filesize_bytes": 7384,
                        "filesize": "7.38 kB",
                        "extension": "jpg",
                        "size": {
                          "width": 225,
                          "height": 225
                        },
                        "mime": "image/jpeg"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "The name for the file."
                  },
                  "tag": {
                    "type": "string",
                    "description": "Description to classify the file type (e.g., generic, product-image)."
                  },
                  "file": {
                    "type": "string",
                    "format": "binary",
                    "description": "The pathway to the file being uploaded."
                  }
                },
                "required": [
                  "name",
                  "tag",
                  "file"
                ]
              },
              "examples": {
                "New Example": {
                  "summary": "New Example",
                  "value": "curl --location 'https://apiprod.fattlabs.com/file' \\\n--header 'Accept: application/json' \\\n--header 'Content-Type: application/json' \\\n--header 'Authorization: Bearer ‘ey…’ \\\n--form 'name=\"Test Energy Drink Image\"' \\\n--form 'tag=\"generic\"' \\\n--form 'file=@\"/Users/testuser/Downloads/energydrink.jpeg\"'}"
                }
              }
            }
          }
        }
      }
    }
  },
  "x-readme": {
    "headers": [],
    "explorer-enabled": true,
    "proxy-enabled": true
  },
  "x-readme-fauxas": true
}
```