Skip to main content

​
POST /api/upload

Uploads a document file and queues it for asynchronous processing. The document will be analyzed and vectorized for use in chat queries.

​
Authentication

This endpoint requires authentication using Laravel Sanctum. Include the bearer token in the Authorization header.

​
Headers

​
Authorization
string
required
Bearer token obtained from login endpoint
​
Content-Type
string
required
Must be multipart/form-data

​
Body parameters

​
file
file
required
The document file to uploadValidation rules:
  • Must be a valid file
  • Allowed MIME types: pdf, txt
  • Maximum file size: 102,400 KB (100 MB)
The upload endpoint accepts PDF and plain text files only. Other file types will be rejected with a validation error.
Files larger than 100 MB will be rejected. Compress or split large documents before uploading.

​
Response

Returns a success message and the created document object.
​
message
string
Success message confirming the upload
​
document
object
The created document object
​
document.id
integer
Unique identifier for the document
​
document.user_id
integer
ID of the user who owns the document
​
document.filename
string
Original filename of the uploaded document
​
document.mime_type
string
MIME type of the document
​
document.path
string
Storage path of the document file
​
document.status
string
Processing status. Will be pending immediately after upload
​
document.vector_id
string
ID of the vector representation (null until processing completes)
​
document.created_at
string
ISO 8601 timestamp when the document was created
​
document.updated_at
string
ISO 8601 timestamp when the document was last updated

​
Processing workflow

After a successful upload:
  1. The file is stored securely in private storage
  2. A document metadata record is created with status: "pending"
  3. An asynchronous job (ProcessDocument) is dispatched to handle vectorization
  4. The document status will be updated as processing progresses
  5. Once complete, the status will be completed and vector_id will be populated
Document processing happens asynchronously. Poll the List documents endpoint to check processing status.

​
Example request

curl -X POST https://api.filebright.com/api/upload \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -F "file=@/path/to/document.pdf"

​
Example response

201 - Created
{
  "message": "File uploaded successfully",
  "document": {
    "id": 3,
    "user_id": 42,
    "filename": "contract.pdf",
    "mime_type": "application/pdf",
    "path": "documents/9a8b7c6d5e4f3g2h1i.pdf",
    "status": "pending",
    "vector_id": null,
    "created_at": "2026-03-03T15:45:30.000000Z",
    "updated_at": "2026-03-03T15:45:30.000000Z"
  }
}
401 - Unauthorized
{
  "message": "Unauthenticated."
}
422 - Validation error
{
  "message": "The file field is required.",
  "errors": {
    "file": [
      "The file field is required."
    ]
  }
}
422 - Invalid file type
{
  "message": "The file must be a file of type: pdf, txt.",
  "errors": {
    "file": [
      "The file must be a file of type: pdf, txt."
    ]
  }
}
422 - File too large
{
  "message": "The file must not be greater than 102400 kilobytes.",
  "errors": {
    "file": [
      "The file must not be greater than 102400 kilobytes."
    ]
  }
}

Build docs developers (and LLMs) love

Get started for freeTalk to us