File uploads

Files never pass through the Spacebring API. You ask the API for an upload, send the file bytes straight to storage, then reference the file when you create or update the object it belongs to.

Upload a file

1. Create the upload. Call the upload endpoint of the object you are working with and declare the file’s mimeType and exact size in bytes. The response carries a key and an upload block with a presigned URL.
   • For a video, also declare its width and height in pixels. An image’s dimensions are read from the file.
   • For a ticket comment or guide attachment, you can also declare the file name shown with it, which defaults to the storage key. A guide attachment is served as a download under its name, so its upload also returns a Content-Disposition header to send.
   {
     "media": {
       "key": "1757585000-6ba7b810-9dad-41d1-80b4-00c04fd430c8",
       "mimeType": "image/jpeg",
       "size": 248113,
       "status": "pending",
       "upload": {
         "method": "PUT",
         "url": "https://…amazonaws.com/1757585000-6ba7b810-…?X-Amz-Signature=…",
         "headers": { "Content-Type": "image/jpeg", "Content-Length": "248113" },
         "expirationDate": "2026-09-11T10:31:00.000Z"
       }
     }
   }
   
2. Send the file. Make a PUT request to upload.url with the raw file bytes as the body and exactly the upload.headers returned. Do not send a multipart form and do not add your Spacebring credentials. Storage rejects the request when the size or type differs from what you declared, or when the URL has passed its expirationDate.
   curl -X PUT "$UPLOAD_URL" \
     -H "Content-Type: image/jpeg" \
     -H "Content-Length: 248113" \
     --data-binary @cover.jpg
   
3. Attach the file. Pass the key on the create or update request of the object. The object response then carries the public url of the file.
   • Event, benefit, product, plan, or delivery: set media[0].key.
   • Resource or post: add { "key": "…" } to media. A resource lists its images in display order, the first being its cover.
   • Company: set logo.key.
   • Contract template: set template.file.key.
   • Ticket comment: add { "key": "…" } to activity.attachments. A comment takes one file.
   • Guide: add the upload’s url to the guide description as a Markdown image, ![alt text](url). A link to any other image stays a plain link.
   • Guide attachment: add { "key": "…" } to attachments.

Errors

• Creating an upload with an unsupported mimeType or a size above the limit returns 400 with a validationError naming the field.
• Attaching a key whose file has not reached storage yet returns 409 with the code fileUploadPending. Wait for the PUT request to finish and retry.
• Attaching a key that is unknown, expired, already attached, or created by another network returns 400 with the code fileUploadNotFound. Create a new upload.
• Attaching an image to a post when the stored file is not a readable image returns 400 with the code fileNotValid. Upload the file again.

In each case the object is not created or updated. Branch on code in the response body, not on the message.

Upload endpoints

Each object type that accepts files has its own upload endpoint and its own limits.