Upload file

POST https://app.sulus.ai/api/v1/agents/{agent_id}/files

Upload a knowledge file (multipart)

Authentication

Send a bearer token created on your dashboard's Developer page:

Authorization: Bearer <YOUR_API_KEY>

Path parameters

agent_id string Required

The agent id (UUID).

Validation: uuid (route-constrained)

Stored in ai_projects.uid

Files

file file Required

The document, max 20 MB. Allowed extensions: txt, md, markdown, csv, json, log, text, pdf, doc, docx, rtf.

Validation: required|file|max:20480

Stored in ai_project_files.path

Errors

Status	Meaning	Body
`404`	Agent not found, or you do not have access to it
`422`	Disallowed extension	`{"message":"Unsupported file type. Allowed: txt, md, markdown, csv, json, log, text, pdf, doc, docx, rtf."}`
`422`	Validation failed	`{"message":"…","errors":{"field":["…"]}}`
`401`	Missing or invalid bearer token
`403`	Feature ai_chat not enabled for the account

Notes

Requires edit access.
Text is extracted and indexed only for txt, md, markdown, csv, json, log, text (capped at 200,000 characters); other allowed types are stored for reference.
The create response uses extracted; the list response uses vector_count / url / preview_kind instead.

curl --request POST \
  --url https://app.sulus.ai/api/v1/agents/{agent_id}/files \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --form 'file=@/path/to/file'

import requests

url = "https://app.sulus.ai/api/v1/agents/{agent_id}/files"
headers = {"Authorization": "Bearer <YOUR_API_KEY>"}
files = {"file": open("/path/to/file", "rb")}

response = requests.post(url, files=files, headers=headers)
print(response.json())

package main

import (
	"fmt"
	"io"
	"net/http"
)

func main() {
	url := "https://app.sulus.ai/api/v1/agents/{agent_id}/files"
	req, _ := http.NewRequest("POST", url, nil)
	req.Header.Add("Authorization", "Bearer <YOUR_API_KEY>")
	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

Response 201

{
    "object": "file",
    "data": {
        "id": 51,
        "project_id": 7,
        "original_name": "faq.md",
        "mime": "text/markdown",
        "size": 6120,
        "created_at": "2026-07-30T14:25:03.000000Z",
        "extractable": true,
        "extracted": true,
        "indexed": true
    }
}

{
    "object": "file",
    "data": {
        "id": 51,
        "project_id": 7,
        "original_name": "faq.md",
        "mime": "text/markdown",
        "size": 6120,
        "created_at": "2026-07-30T14:25:03.000000Z",
        "extractable": true,
        "extracted": true,
        "indexed": true
    }
}