Presigned URL
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
file_name: '<string>',
content_type: '<string>',
content_length_bytes: 123,
content_hash: '<string>'
})
};
fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url"
payload = {
"file_name": "<string>",
"content_type": "<string>",
"content_length_bytes": 123,
"content_hash": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"file_name": "<string>",
"content_type": "<string>",
"content_length_bytes": 123,
"content_hash": "<string>"
}
'{
"upload_url": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"upload_headers": {}
}Presigned URL
Generate a presigned PUT URL to upload an evidence file before submitting a response
POST
/
v1
/
custom-kpi-datasets
/
{dataset_id}
/
responses
/
attachments
/
presigned-url
Presigned URL
const options = {
method: 'POST',
headers: {
'x-api-key': '<x-api-key>',
'x-organization-id': '<x-organization-id>',
'Content-Type': 'application/json'
},
body: JSON.stringify({
file_name: '<string>',
content_type: '<string>',
content_length_bytes: 123,
content_hash: '<string>'
})
};
fetch('https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));import requests
url = "https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url"
payload = {
"file_name": "<string>",
"content_type": "<string>",
"content_length_bytes": 123,
"content_hash": "<string>"
}
headers = {
"x-api-key": "<x-api-key>",
"x-organization-id": "<x-organization-id>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)curl --request POST \
--url https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url \
--header 'Content-Type: application/json' \
--header 'x-api-key: <x-api-key>' \
--header 'x-organization-id: <x-organization-id>' \
--data '
{
"file_name": "<string>",
"content_type": "<string>",
"content_length_bytes": 123,
"content_hash": "<string>"
}
'{
"upload_url": "<string>",
"file_id": "<string>",
"file_name": "<string>",
"upload_headers": {}
}← Custom KPI
Generate a presigned S3 PUT URL for uploading an evidence file. Use this before calling Submit Response — upload the file to the returned URL, then include the
file_id in your submission’s attachment_file_ids.
Request
Headers
string
required
Your API key for authenticationExample:
sk_live_1234567890abcdefstring
required
Your organization UUIDExample:
a8315ef3-dd50-43f8-b7ce-d839e68d51faPath Parameters
string
required
UUID of the parent dataset
Query Parameters
string
Send
sha256 to receive upload_headers: the exact headers your PUT to upload_url must carry. When you also
send content_hash, they may include x-amz-checksum-sha256, so storage refuses any bytes other than the ones you
hashed (400 BadDigest). Any other value is ignored.Body Parameters
string
required
Original file name (1–255 characters)
string
MIME type of the file (e.g.
application/pdf, image/png). Max 255 characters.integer
required
File size in bytes. Must be between 1 and 10 485 760 (10 MB).
string
SHA-256 of the file’s bytes, as 64 lowercase hex characters. Optional.
Response
Returns the presigned upload URL and file metadata (HTTP 201).string
Presigned S3 PUT URL — upload your file here with a PUT request
string
File UUID — include this in
attachment_file_ids when submittingstring
Echoed file name
object | null
Only with
upload_checksum=sha256: the headers to send, unchanged, with the PUT to upload_url (they are part of
its signature). null otherwise.Example
# 1. Get the presigned URL
curl -X POST "https://api.dcycle.io/v1/custom-kpi-datasets/${DATASET_ID}/responses/attachments/presigned-url" \
-H "x-api-key: ${DCYCLE_API_KEY}" \
-H "x-organization-id: ${DCYCLE_ORG_ID}" \
-H "Content-Type: application/json" \
-d '{
"file_name": "energy-audit-2025.pdf",
"content_type": "application/pdf",
"content_length_bytes": 2048576
}'
# 2. Upload the file to the presigned URL
curl -X PUT "${UPLOAD_URL}" \
-H "Content-Type: application/pdf" \
--data-binary @energy-audit-2025.pdf
import requests
import os
headers = {
"x-api-key": os.getenv("DCYCLE_API_KEY"),
"x-organization-id": os.getenv("DCYCLE_ORG_ID"),
"Content-Type": "application/json",
}
dataset_id = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
file_path = "energy-audit-2025.pdf"
file_size = os.path.getsize(file_path)
# Step 1: Get presigned URL
presign = requests.post(
f"https://api.dcycle.io/v1/custom-kpi-datasets/{dataset_id}/responses/attachments/presigned-url",
headers=headers,
json={
"file_name": "energy-audit-2025.pdf",
"content_type": "application/pdf",
"content_length_bytes": file_size,
},
).json()
# Step 2: Upload the file
with open(file_path, "rb") as f:
requests.put(presign["upload_url"], data=f, headers={"Content-Type": "application/pdf"})
print(f"Uploaded! file_id: {presign['file_id']}")
# Use presign["file_id"] in attachment_file_ids when submitting
const axios = require('axios');
const fs = require('fs');
const headers = {
'x-api-key': process.env.DCYCLE_API_KEY,
'x-organization-id': process.env.DCYCLE_ORG_ID,
'Content-Type': 'application/json',
};
const datasetId = 'a1b2c3d4-e5f6-7890-abcd-ef1234567890';
const fileBuffer = fs.readFileSync('energy-audit-2025.pdf');
// Step 1: Get presigned URL
const { data: presign } = await axios.post(
`https://api.dcycle.io/v1/custom-kpi-datasets/${datasetId}/responses/attachments/presigned-url`,
{
file_name: 'energy-audit-2025.pdf',
content_type: 'application/pdf',
content_length_bytes: fileBuffer.length,
},
{ headers }
);
// Step 2: Upload the file
await axios.put(presign.upload_url, fileBuffer, {
headers: { 'Content-Type': 'application/pdf' },
});
console.log(`Uploaded! file_id: ${presign.file_id}`);
// Use presign.file_id in attachment_file_ids when submitting
Successful Response
{
"upload_url": "https://dcycle-custom-kpi.s3.eu-west-1.amazonaws.com/attachments/...?X-Amz-Algorithm=AWS4-HMAC-SHA256&...",
"file_id": "a1b2c3d4-0000-0000-0000-000000000001",
"file_name": "energy-audit-2025.pdf"
}
Common Errors
401 Unauthorized
Cause: Missing or invalid API key{"detail": "Invalid API key for organization", "code": "INVALID_API_KEY"}
403 Forbidden
Cause: The authenticated user is not a member of the organization{"detail": "Logged User is not Member of Organization", "code": "LOGGED_USER_NOT_MEMBER"}
422 Validation Error
Cause: File exceeds 10 MB limit{
"detail": [
{
"loc": ["body", "content_length_bytes"],
"msg": "ensure this value is less than or equal to 10485760",
"type": "value_error.number.not_le"
}
]
}
Related Endpoints
Submit Response
Submit values with the uploaded attachments
Edit Values
Update values for a campaign-assignment
Was this page helpful?