Docs
API Reference

Attachments

Presigned upload and download URL flows for document attachments.

Attachments use a presigned URL model. Integrators first request a temporary URL from Carrot API, then upload or download file data directly with the returned URL.

Create upload URL

PUT
/documents/{documentId}/attachments/{fileName}

Authorization

OAuth2ClientCredentials
AuthorizationBearer <token>

OAuth 2.0 Client Credentials authentication.

In: header

Path Parameters

documentId*string

Document ID the file belongs to

fileName*string

File name

Header Parameters

Authorization*string

Authorization bearer token

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

curl -X PUT "https://api.carrot.eco/documents/28b04f62-8fe2-4332-b854-fe8a922788b5/attachments/imagem.png" \  -H "Authorization: string" \  -H "Content-Type: application/json" \  -d '{    "contentLength": 2064,    "contentType": "image/png"  }'
{
  "url": "https://bucket-palantir-files-2dfd6ab.s3.us-east-1.amazonaws.com/attachments/document/2b02cba4-2abb-4ae8-b938-9a8dfa21d07c/sangalli3.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIASRVXQK6OAHP7MVMF%2F20230828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230828T200038Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIDVJGCaQA%2FGNQGUZv1DoYBQP9P7teWjZ4UbB37fBzhfJAiEApDN2da7RciY%2B8JRyF70PfD2TQ6SnXGKkvLgtb%2Bped8Mq%2FQIIlf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAAGgwxNzU0MDQ3NjcxMzIiDAIUC5rUpbaLUK7Y0yrRAnnWUVlCZA3MB5KhHLwxiSX77JTm6FGCrMCzrGzhjFk2LvHnv8yZv3WJhmeuahHZX%2BND5Iyl6sAhlehDmX9fWwax0vf1caEsbb2xHHkJfXKYEhvlbJ6B0GRNUYOz4dHZGFzTG0PUX6sPxrZHyDmk2MiCZU9ruX1oOpMYqGcZv0hRVS5RzCneo18eoGTEq6M1Mikv%2BT%2BFX8iTcwPP9DftFz44CWKcZpuMhOHlQEBuwJYHrgUDbl75WgEkuKW2mAs2avn8vQl4DtG08gJd1WKRqILKKVdfxZ7TYFjaEzAdR%2Fh3%2B0%2FZDwvg5JcGqInX2HWFu%2BoATN%2Bf4OFXvohdzOGir0NTeNovbE5ParKVsqE23lC9dhpqRnl3pJlNL9xi4JqBzyNfaanfM6A04cYpt6iiDTEvta4IKxGjyCkADWQzC7b92jOCtHnhF87NGg%2FHjpP2PK8wvvmzpwY6ngHCnf9yb1f4jgyRBvP9JOPetR9vjY31ekAabs3%2B2VFIGJtUiRETh1aOuD%2BtD3pjnw%2F04rg3%2FKL3kGiDDmcNIy%2BCfaMdNjJSkQ0y8SsoX3joXTs2pd55bs4QTlOFX4kjQTzllospaUFTVewsNJe3%2Fui1yKKKPZ%2BQG7CkdHGLCUUQjqSEVzUSXtHy8DFpNDLzZKB1MlwDNLSBqW1C2PA4Ng%3D%3D&X-Amz-Signature=6f299bc60c53f8d4edca622afd61a471a533d68d60e51fb2a34ac010b4e1419d&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject"
}
Empty
Empty
Empty

Use PUT /documents/{documentId}/attachments/{fileName} to request an upload URL. Send:

  • contentLength (bytes)
  • contentType (MIME type)

After receiving the URL:

  1. Send PUT to the presigned URL with the file in binary format.
  2. Include the same Content-Type declared in the URL request.
  3. No Authorization header is required for the presigned upload call.

Get download URL

GET
/documents/{documentId}/attachments/{fileName}

Authorization

OAuth2ClientCredentials
AuthorizationBearer <token>

OAuth 2.0 Client Credentials authentication.

In: header

Path Parameters

documentId*string

Document ID the attachment belongs to

fileName*string

Attachment file name

Header Parameters

Authorization*string

Authorization bearer token

Response Body

application/json

curl -X GET "https://api.carrot.eco/documents/28b04f62-8fe2-4332-b854-fe8a922788b5/attachments/imagem.png" \  -H "Authorization: string"
{
  "url": "https://bucket-palantir-files-2dfd6ab.s3.us-east-1.amazonaws.com/attachments/document/2b02cba4-2abb-4ae8-b938-9a8dfa21d07c/sangalli3.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=ASIASRVXQK6OAHP7MVMF%2F20230828%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20230828T200038Z&X-Amz-Expires=604800&X-Amz-Security-Token=IQoJb3JpZ2luX2VjEMz%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FwEaCXVzLWVhc3QtMSJHMEUCIDVJGCaQA%2FGNQGUZv1DoYBQP9P7teWjZ4UbB37fBzhfJAiEApDN2da7RciY%2B8JRyF70PfD2TQ6SnXGKkvLgtb%2Bped8Mq%2FQIIlf%2F%2F%2F%2F%2F%2F%2F%2F%2F%2FARAAGgwxNzU0MDQ3NjcxMzIiDAIUC5rUpbaLUK7Y0yrRAnnWUVlCZA3MB5KhHLwxiSX77JTm6FGCrMCzrGzhjFk2LvHnv8yZv3WJhmeuahHZX%2BND5Iyl6sAhlehDmX9fWwax0vf1caEsbb2xHHkJfXKYEhvlbJ6B0GRNUYOz4dHZGFzTG0PUX6sPxrZHyDmk2MiCZU9ruX1oOpMYqGcZv0hRVS5RzCneo18eoGTEq6M1Mikv%2BT%2BFX8iTcwPP9DftFz44CWKcZpuMhOHlQEBuwJYHrgUDbl75WgEkuKW2mAs2avn8vQl4DtG08gJd1WKRqILKKVdfxZ7TYFjaEzAdR%2Fh3%2B0%2FZDwvg5JcGqInX2HWFu%2BoATN%2Bf4OFXvohdzOGir0NTeNovbE5ParKVsqE23lC9dhpqRnl3pJlNL9xi4JqBzyNfaanfM6A04cYpt6iiDTEvta4IKxGjyCkADWQzC7b92jOCtHnhF87NGg%2FHjpP2PK8wvvmzpwY6ngHCnf9yb1f4jgyRBvP9JOPetR9vjY31ekAabs3%2B2VFIGJtUiRETh1aOuD%2BtD3pjnw%2F04rg3%2FKL3kGiDDmcNIy%2BCfaMdNjJSkQ0y8SsoX3joXTs2pd55bs4QTlOFX4kjQTzllospaUFTVewsNJe3%2Fui1yKKKPZ%2BQG7CkdHGLCUUQjqSEVzUSXtHy8DFpNDLzZKB1MlwDNLSBqW1C2PA4Ng%3D%3D&X-Amz-Signature=6f299bc60c53f8d4edca622afd61a471a533d68d60e51fb2a34ac010b4e1419d&X-Amz-SignedHeaders=content-length%3Bhost&x-id=PutObject"
}
Empty
Empty
Empty

Use GET /documents/{documentId}/attachments/{fileName} to request a temporary download URL. Then perform a standard GET on the returned URL to fetch the file.

Limits and behavior

  • Maximum file size per upload: 10 MB.
  • Attachments are typically referenced later from event payloads.

See File Uploads for practical integration patterns.

Events

Append immutable events to document timelines in the Carrot API.

Errors

Error response shape, error codes, limits, and recovery patterns.

On this page

Create upload URL
Get download URL
Limits and behavior