Upload a document

Document uploads use three steps: request a presigned URL, upload the file to private storage, then create the document record. Document objects under documents/ are not publicly readable — preview and download always go through signed SquadVault URLs.

Flow

1. Request a presigned upload URL

curl -X POST "https://api.squadvault.xyz/v1/uploads/document-file" \
  -H "x-api-key: sv_org_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationId": "YOUR_ORG_ID",
  "contentType": "application/pdf",
  "sizeBytes": 102400
}'

Response:

{
  "key": "documents/YOUR_ORG_ID/uuid.pdf",
  "fileRef": "s3://your-bucket/documents/YOUR_ORG_ID/uuid.pdf",
  "uploadUrl": "https://...presigned..."
}

Map fields when creating the document: fileKey ← key, fileUrl ← fileRef. The API overwrites fileUrl with a private storage reference. sizeBytes must match the exact byte length of the file you PUT in step 2.

2. Upload the file

curl -X PUT "<uploadUrl>" \
  -H "Content-Type: application/pdf" \
  --data-binary @playbook.pdf

Use the same Content-Type and byte size you requested in step 1.

3. Create the document record

curl -X POST "https://api.squadvault.xyz/v1/documents" \
  -H "x-api-key: sv_org_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "organizationId": "YOUR_ORG_ID",
  "name": "Playbook Q3",
  "fileUrl": "<fileRef>",
  "fileKey": "<key>",
  "contentType": "application/pdf",
  "sizeBytes": 102400,
  "tags": ["playbook"]
}'

To download or preview later, call GET /documents/{documentId}/download or /preview — never use fileUrl as a public HTTP link.

Allowed content types

application/pdf
application/msword
application/vnd.openxmlformats-officedocument.wordprocessingml.document
application/vnd.ms-excel
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
text/plain
image/jpeg, image/png, image/webp, image/gif

Maximum file size depends on the organization plan (enforced server-side).

JavaScript example

const sizeBytes = fileBuffer.byteLength;

const uploadResponse = await fetch(
  "https://api.squadvault.xyz/v1/uploads/document-file",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SQUADVAULT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      organizationId: "YOUR_ORG_ID",
      contentType: "application/pdf",
      sizeBytes,
    }),
  },
);

const { key, fileRef, uploadUrl } = await uploadResponse.json();

await fetch(uploadUrl, {
  method: "PUT",
  headers: { "Content-Type": "application/pdf" },
  body: fileBuffer,
});

const documentResponse = await fetch(
  "https://api.squadvault.xyz/v1/documents",
  {
    method: "POST",
    headers: {
      "x-api-key": process.env.SQUADVAULT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      organizationId: "YOUR_ORG_ID",
      name: "Playbook Q3",
      fileUrl: fileRef,
      fileKey: key,
      contentType: "application/pdf",
      sizeBytes,
      tags: ["playbook"],
    }),
  },
);

const document = await documentResponse.json();

Required permission for both upload URL and document create: document:create.

Guides

Teams

Players

Documents

Tryout Applications

Uploads