Upload

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

Upload an entity logo

POST/upload/image

Upload or replace the current entity logo. The x-entity-id header selects the entity whose logo is updated.
Supports PNG, JPG, WEBP, and GIF formats. Maximum file size: 10MB.
The image is automatically optimized, the previous entity logo is replaced, and secure URLs are returned for 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/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
}, { entity_id: 'YOUR_ENTITY_ID' });

console.log(response);

Response

Returns

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"
}