Skip to main content
POST
/
api
/
files
Create File
curl --request POST \
  --url https://api.example.com/api/files \
  --header 'Authorization: <authorization>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "project_id": 123,
  "name": "<string>",
  "mime_type": "<string>",
  "size_bytes": 123
}
'
{
  "data": {
    "file": {
      "id": 1,
      "project_id": 4,
      "name": "checkout-flow.docx",
      "upload_url": "https://...r2.cloudflarestorage.com/project-resources/...?X-Amz-...",
      "status": "pending",
      "description": null,
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size_bytes": 245000,
      "created_by": "user-id",
      "created_at": "2026-03-20T10:30:00Z",
      "updated_at": "2026-03-20T10:30:00Z"
    }
  }
}
Creates a file record and returns a presigned upload URL. This is step 1 of the upload flow:
  1. Create — POST /api/files → returns upload_url
  2. Upload — PUT the file to upload_url
  3. Confirm — PATCH /api/files/{id} with {"status": "uploaded"}
Files remain in pending status until confirmed. Only uploaded files appear in list results.

​
Request

​
Authorization
string
required
Bearer token for authentication. Format: Bearer <your-api-key>
​
project_id
number
required
The project ID to associate the file with.
​
name
string
required
Display name for the file (typically the file name).
​
mime_type
string
MIME type of the file.
​
size_bytes
number
File size in bytes.

​
Response

​
data.file
object
The created file with a presigned upload URL.
{
  "data": {
    "file": {
      "id": 1,
      "project_id": 4,
      "name": "checkout-flow.docx",
      "upload_url": "https://...r2.cloudflarestorage.com/project-resources/...?X-Amz-...",
      "status": "pending",
      "description": null,
      "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
      "size_bytes": 245000,
      "created_by": "user-id",
      "created_at": "2026-03-20T10:30:00Z",
      "updated_at": "2026-03-20T10:30:00Z"
    }
  }
}

​
Full upload example

# Step 1: Create file and get upload URL
curl -s -X POST \
  https://dash.empirical.run/api/files \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{
    "project_id": 4,
    "name": "checkout-flow.docx",
    "mime_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
    "size_bytes": 245000
  }'

# Step 2: Upload file to the presigned URL (from response.data.file.upload_url)
curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/vnd.openxmlformats-officedocument.wordprocessingml.document" \
  --data-binary @checkout-flow.docx

# Step 3: Confirm upload
curl -X PATCH \
  https://dash.empirical.run/api/files/1 \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMPIRICALRUN_KEY" \
  -d '{"status": "uploaded"}'