API Reference

The reference below covers every endpoint in the Files API. Code examples are generated automatically; the live playground is disabled to prevent accidental writes to production from the docs site.

GET/api/v1/files

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Query Parameters

entity*string

The record type. Case-insensitive, so contact works too.

Value in

"CONTACT"
"LEAD"
"DEAL"
"COMPANY"
"QUOTE"
"CONTRACT"
"TASK"
"NOTE"
"CASE"
"CAMPAIGN"
"OFFERING"

recordId*string

The record's agentlyleads ID, or its externalId. Quotes, contracts, cases and campaigns have no externalId and must be addressed by ID.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/files?entity=CONTACT&recordId=string"

{  "files": [    {      "id": "cmq3file0alk34567890",      "entity": "CONTACT",      "recordId": "cmq2cont0alk34567891",      "kind": "attachment",      "fileName": "signed-nda.pdf",      "contentType": "application/pdf",      "size": 184320,      "createdAt": "2026-09-27T14:02:00.000Z"    }  ]}

{  "error": "entity must be one of: CONTACT, LEAD, DEAL, COMPANY, QUOTE, CONTRACT, TASK, NOTE, CASE, CAMPAIGN, OFFERING."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:files."}

{  "error": "Contact not found."}

{  "error": "Rate limit exceeded."}

POST/api/v1/files

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

TypeScript Definitions

Use the request body type in TypeScript.

file*file

The file itself. Its own filename and type are used unless overridden.

Formatbinary

entity*string

The record type. Case-insensitive.

Value in

"CONTACT"
"LEAD"
"DEAL"
"COMPANY"
"QUOTE"
"CONTRACT"
"TASK"
"NOTE"
"CASE"
"CAMPAIGN"
"OFFERING"

recordId*string

The record's agentlyleads ID, or its externalId where the record type has one.

fileName?string

Optional. Overrides the filename sent with the file part.

Lengthlength <= 255

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/files" \  -H "Content-Type: application/json" \  -d '{    "entity": "contact",    "recordId": "hs_contact_123",    "fileName": "signed-nda.pdf",    "contentType": "application/pdf",    "contentBase64": "JVBERi0xLjcKJeLjz9MK..."  }'

{  "file": {    "id": "cmq3file0alk34567890",    "entity": "CONTACT",    "recordId": "cmq2cont0alk34567891",    "kind": "attachment",    "fileName": "signed-nda.pdf",    "contentType": "application/pdf",    "size": 184320,    "createdAt": "2026-09-27T14:02:00.000Z"  }}

{  "error": "Files can only be added to a campaign before it sends."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:files."}

{  "error": "Deal not found."}

{  "error": "That file is too large for a direct upload (10 MB). Use POST /api/v1/files/upload-url for files up to 50 MB."}

{  "error": "Rate limit exceeded."}

{  "error": "File storage isn't configured for this workspace."}

POST/api/v1/files/upload-url

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

entity*string

The record type. Case-insensitive.

Value in

"CONTACT"
"LEAD"
"DEAL"
"COMPANY"
"QUOTE"
"CONTRACT"
"TASK"
"NOTE"
"CASE"
"CAMPAIGN"
"OFFERING"

recordId*string

The record's agentlyleads ID, or its externalId where the record type has one.

fileName*string

Lengthlength <= 255

contentType*string

The MIME type. Send the same value as the Content-Type of your PUT.

Lengthlength <= 150

size*integer

Size in bytes. At most 50 MB (52,428,800 bytes).

Range1 <= value <= 52428800

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/files/upload-url" \  -H "Content-Type: application/json" \  -d '{    "entity": "CONTACT",    "recordId": "string",    "fileName": "catalog-2026.pdf",    "contentType": "application/pdf",    "size": 31457280  }'

{  "uploadUrl": "https://agentlyleads-files.s3.amazonaws.com/cmq1wksp0alk34567890/deal/cmq2deal0alk34567890/1727445720000-3f9a1c2b-catalog-2026.pdf?X-Amz-Signature=...",  "s3Key": "cmq1wksp0alk34567890/deal/cmq2deal0alk34567890/1727445720000-3f9a1c2b-catalog-2026.pdf",  "recordId": "cmq2deal0alk34567890",  "expiresInSeconds": 300}

{  "error": "contentType is required."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:files."}

{  "error": "Offering not found."}

{  "error": "Offering images are limited to 10 MB."}

{  "error": "Rate limit exceeded."}

{  "error": "File storage isn't configured for this workspace."}

GET/api/v1/files/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The file ID, as returned in file.id or files[].id.

Response Body

`application/json`

curl -X GET "https://example.com/api/v1/files/string"

{  "file": {    "id": "cmq3file0alk34567890",    "entity": "CONTACT",    "recordId": "cmq2cont0alk34567891",    "kind": "attachment",    "fileName": "signed-nda.pdf",    "contentType": "application/pdf",    "size": 184320,    "createdAt": "2026-09-27T14:02:00.000Z",    "downloadUrl": "https://agentlyleads-files.s3.amazonaws.com/...&X-Amz-Signature=...",    "downloadUrlExpiresAt": "2026-09-27T14:07:00.000Z"  }}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: read:files."}

{  "error": "File not found."}

{  "error": "Rate limit exceeded."}

{  "error": "File storage isn't configured for this workspace."}

DELETE/api/v1/files/{id}

Authorization

BearerAuth

AuthorizationBearer <token>

Pass an API key issued from the agentlyleads workspace settings. Example: Authorization: Bearer alk_live_xxxxxxxxxxxx

In: header

Path Parameters

id*string

The file ID.

Response Body

`application/json`

curl -X DELETE "https://example.com/api/v1/files/string"

{  "deleted": 1,  "id": "cmq3file0alk34567890"}

{  "error": "Files can't be removed from a campaign that has already sent."}

{  "error": "Invalid or missing API key."}

{  "error": "API key missing required scope: write:files."}

{  "error": "File not found."}

{  "error": "Rate limit exceeded."}

API Reference

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

201application/json

400application/json

401application/json

403application/json

404application/json

413application/json

429application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

413application/json

429application/json

503application/json

200application/json

401application/json

403application/json

404application/json

429application/json

503application/json

200application/json

400application/json

401application/json

403application/json

404application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`