Upload

File upload endpoints for images and documents. All uploads are scoped to entities.

Upload image

POST/upload/image

Upload an image file to cloud storage.
Supports PNG, JPG, WEBP, and GIF formats. Maximum file size: 5MB.
Images are automatically optimized and stored in entity-specific folders.
Returns secure URLs for use in entity settings, invoices, and other documents.

Request

Header parameters

entity_idstringoptional

Entity ID on which the request is made. Auto-selected when only one entity exists, required when multiple entities exist.

Body parameters

filestring<binary>required

Image file to upload (PNG, JPG, WEBP, GIF)

import SpaceInvoices from '@spaceinvoices/js-sdk';
import fs from 'fs';

const sdk = new SpaceInvoices('YOUR_API_KEY');

// Read file as Buffer
const fileBuffer = fs.readFileSync('/path/to/image.png');
const file = new File([fileBuffer], 'image.png', { type: 'image/png' });

const response = await sdk.upload.uploadImage({
  file
});

console.log(response);

Response

Returns

urlstring<uri>

secure_urlstring<uri>

public_idstring

secureUrlstring<uri>

publicIdstring

formatstring

widthnumber

heightnumber

bytesnumber

entity_idstring

json

{
  "url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secure_url": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "public_id": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "secureUrl": "https://storage.example.com/si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "publicId": "si/entities/ent_507f1f77bcf86cd799439011/logos/logo_ent_507f1f77bcf86cd799439011_1741689600000.png",
  "format": "png",
  "width": 576,
  "height": 192,
  "bytes": 45678,
  "entity_id": "ent_507f1f77bcf86cd799439011",
  "filename": "company-logo.png",
  "mime_type": "image/png"
}