Guides
API reference
MCP server
Changelogcurl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/attachments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fileName": "pricing-2026.pdf",
"fileSize": 482113,
"mimeType": "application/pdf",
"url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"storageProvider": "S3",
"storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
]
}
'{
"meta": {
"message": "Attachment created successfully."
},
"data": {
"_id": "6729c0d4e5f6a7b8c9d0e1f2",
"organizationId": "66a0f1e2d3c4b5a697887766",
"fileName": "pricing-2026.pdf",
"fileSize": 482113,
"mimeType": "application/pdf",
"url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"storageProvider": "S3",
"storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"isKbFile": false,
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Create a file
Records a file you uploaded with an upload URL, as a knowledge base file or as a file attached to records, tasks or other resources. This is the last of three steps; see the steps above.
Knowledge base files. With isKbFile: true the file is linked to your workspace
automatically, and Heliyos copies it into the workers’ workspace and extracts its text so
workers can read it. Text extraction can finish a little after this call returns.
Retries are safe. Creating a file again with the same storageKey returns the file
already created, unchanged, instead of a second one.
The file is checked before anything is written: storageKey must be inside your workspace’s
folder and url must point at exactly that key. Every entry in relationships must name a
resource of your workspace.
curl --request POST \
--url https://api-prod.heliyos.ai/v1/platform/attachments \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"fileName": "pricing-2026.pdf",
"fileSize": 482113,
"mimeType": "application/pdf",
"url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"storageProvider": "S3",
"storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
]
}
'{
"meta": {
"message": "Attachment created successfully."
},
"data": {
"_id": "6729c0d4e5f6a7b8c9d0e1f2",
"organizationId": "66a0f1e2d3c4b5a697887766",
"fileName": "pricing-2026.pdf",
"fileSize": 482113,
"mimeType": "application/pdf",
"url": "https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"storageProvider": "S3",
"storageKey": "66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf",
"isKbFile": false,
"relationships": [
{
"objectId": "66f1a8c3e4b0a1b2c3d4e5f6",
"schemaId": "66a0f1e2d3c4b5a697880001",
"objectType": "company"
}
],
"metadata": {
"created": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
},
"updated": {
"at": "2026-11-04T09:30:00.000Z",
"by": "66a0f1e2d3c4b5a697881111"
}
}
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}{
"message": "<string>",
"error": {
"code": "VALIDATION_FAILED",
"message": "<string>",
"details": "<unknown>"
}
}Get an upload URL
Upload the bytes
PUT the file to presignedUrl with the same Content-Type and Content-Length, without
your API key.Create the file
storageKey set to fileKey, url set to
https://{bucketName}.s3.amazonaws.com/{fileKey}, storageProvider set to S3, and the
same fileName, mimeType and fileSize.heliyos_files_upload.Authorizations
A workspace API key, sent as Authorization: Bearer heliyos_.... Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in.
Body
The name shown for the file. Usually the same name you sent for the upload URL.
"pricing-2026.pdf"
The file's size in bytes, 0 to 26,214,400 (25 MB). Send the size you uploaded.
0 <= x <= 26214400482113
The file's content type. Send the mimeType you uploaded with.
"application/pdf"
https://{bucketName}.s3.amazonaws.com/{fileKey}, built from the upload URL response. HTTPS only, with no port, credentials, query or fragment. Up to 2,048 characters.
2048"https://example-bucket.s3.amazonaws.com/66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf"
The storage provider. Send S3.
"S3"
The fileKey from the upload URL response. A key outside your workspace's folder is refused.
"66a0f1e2d3c4b5a697887766/objects/company/1762248600000-pricing-2026.pdf"
Optional. The resources to attach the file to: records (company, people, deal or a custom object's type, with schemaId), task, note, comment, interaction, meeting, email, chat or list, up to 200 entries. Each must belong to your workspace. An organization entry may only name your own workspace.
Show child attributes
Show child attributes
true to add the file to the knowledge base, where workers read it. Defaults to false, a file attached to the resources in relationships.
false
Optional. A short description of the file. May be empty.
"2026 list prices and discount bands."
Was this page helpful?