canonical: https://jentic.com/apis/hubspot.com/hubspot-files

# HubSpot Files

The HubSpot Files API uploads and manages files in the HubSpot file manager - the storage layer behind email images, CMS pages, knowledge base attachments, and CRM record uploads. It supports direct multipart uploads, asynchronous import-from-URL for large external files, folder organisation, and signed-URL generation for private file access. Files can be checked for duplicates by stat path, retrieved by id, GDPR-deleted, and listed by folder, giving agents full control over the asset library that other HubSpot APIs reference by file id.

## For AI agents

Upload, organise, and retrieve files in the HubSpot file manager so other HubSpot APIs (CMS, marketing email, CRM) can reference them by file id or signed URL.

## Scope

Does not transcode video, perform on-the-fly image transformations, or manage CRM records - use for HubSpot file manager uploads, organisation, and retrieval only.

## Capabilities

- Upload a file directly via multipart, with folder placement and access level set in one call
- Import a large file asynchronously from an external URL without holding open a long upload connection
- Generate a time-limited signed URL for private files so they can be served to authenticated viewers
- Organise files by folder - create folders, fetch a folder by id, and list contents
- Check whether a file already exists at a given path using the stat endpoint to avoid duplicates
- GDPR-delete a file and its derivatives so it is removed from all HubSpot caches and references

## Use cases

### Email and CMS Asset Hosting

Marketing emails and CMS pages need a reliable asset store with stable URLs. Upload images and PDFs through the Files API and reference the returned file id or public URL from marketing email and CMS page payloads. The API handles folder organisation, public/private access control, and CDN distribution, so assets render reliably across thousands of email sends and page views.

Example prompt: Call POST /files/v3/files with a multipart body containing the image, folderPath=/marketing/q3, and access=PUBLIC_INDEXABLE.

### Async External File Import

Migrating a CMS or replicating a campaign often means importing thousands of files from existing public URLs. POST /files/v3/files/import-from-url/async kicks off a server-side fetch so your client does not need to download and re-upload large files. The endpoint returns a task id you can poll, freeing the agent to do other work while HubSpot streams the file directly from source.

Example prompt: Call POST /files/v3/files/import-from-url/async with url=https://example.com/asset.png and folderPath=/migration.

### Private File Sharing with Signed URLs

Files marked as private are not served from a public URL - they require a signed URL with an expiry. Call the signed-url endpoint to mint a short-lived link an agent can hand to an authenticated viewer (for example, an internal dashboard rendering customer attachments) without making the file publicly indexable. Useful for support attachments and gated content.

Example prompt: Call GET /files/v3/files/{fileId}/signed-url with size=preview to retrieve a short-lived URL for the asset.

### AI Agent Attachment Workflow via Jentic

An AI agent processing customer support tickets uploads attachments to HubSpot for record-keeping, generates a signed URL, and attaches it to the ticket. The agent searches Jentic for upload and signed-URL operations, loads each schema, and executes both calls in sequence. Jentic isolates the HubSpot OAuth token so the agent never handles raw credentials.

Example prompt: Search Jentic for "upload file to hubspot", load the schema for POST /files/v3/files, execute the upload, then call GET /files/v3/files/{fileId}/signed-url.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | /files/v3/files | Upload a file via multipart |
| GET | /files/v3/files/{fileId} | Retrieve file metadata by id |
| DELETE | /files/v3/files/{fileId}/gdpr-delete | GDPR-delete a file and its derivatives |
| POST | /files/v3/files/import-from-url/async | Import a file from an external URL asynchronously |
| GET | /files/v3/files/{fileId}/signed-url | Generate a signed URL for a private file |
| GET | /files/v3/files/stat/{path} | Check whether a file exists at a given path |
| POST | /files/v3/folders | Create a folder |
| GET | /files/v3/folders/{folderId} | Retrieve a folder by id |

## Key resources

- **Files** — Individual file objects - uploaded, retrieved by id, signed, deleted.
- **Folders** — Folder hierarchy for organising files in the file manager.
- **Imports** — Asynchronous import jobs for fetching files from external URLs.

## Why Jentic

- **Setup:** Wiring HubSpot Files by hand means learning its OAuth2 access token auth, targeting the api.hubapi.com host, and handling multipart uploads and folder organisation yourself. Through Jentic you install once, import HubSpot Files from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** The Files API puts the file id in the URL path (/files/v3/files/{fileId}), so a rule can pin your agent to reading one file and its signed URL. You choose the operations it may call, so the GDPR delete is not included unless you add it.
- **Credential handling:** Your HubSpot access token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a file to HubSpot' or 'get a signed file URL', and Jentic returns the matching Files operation with its multipart input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Marketing Emails** — Reference uploaded files by id in marketing email content blocks
- **CMS Pages** — Reference uploaded files in CMS page content modules
- **Cloudinary Upload API** — Dedicated media upload and CDN with richer image processing than HubSpot's file manager
- **CMS Media Bridge** — Bridge external media providers into HubSpot file references

## FAQ

### What authentication does the Files API use?

The API accepts HubSpot OAuth 2.0 access tokens or private app tokens, sent as Bearer in the Authorization header. Through Jentic, the token is stored encrypted in your Jentic One instance and injected at execution time so the agent never sees the raw secret.

### Can I upload a file by URL instead of streaming it through my client?

Yes. Call POST /files/v3/files/import-from-url/async with the source URL and a target folderPath. HubSpot fetches the file server-side and returns a task id you can poll for completion.

### How do I serve a private HubSpot file to an authenticated viewer?

Call GET /files/v3/files/{fileId}/signed-url to mint a short-lived URL. Provide a size parameter to request a derivative if the file is an image.

### What are the rate limits for the Files API?

Account-level limits are 100 requests per 10 seconds across HubSpot's authenticated APIs, with daily caps that depend on the subscription tier. Multipart uploads count once per request regardless of file size.

### How do I upload a file through Jentic?

Run pip install jentic, search for "upload file to hubspot", load the schema for POST /files/v3/files, and execute with the multipart body and folderPath. Get started with Jentic One, the self-hosted execution layer.

### Does GDPR delete remove cached derivatives like image thumbnails?

Yes. The DELETE /files/v3/files/{fileId}/gdpr-delete endpoint removes the file along with its generated derivatives so the asset is no longer served from any HubSpot URL or thumbnail cache.

### Can I limit what my agent is allowed to do with the HubSpot Files API?

Yes. Jentic One is self-hosted, so your own rules decide which Files operations and credentials the agent may use. Because the file id sits in the URL path, such as /files/v3/files/{fileId}, you can pin the agent to reading a single file and minting its signed URL while leaving out uploads, folder changes, or the GDPR delete. Only the operations you explicitly grant are callable, and your HubSpot token stays encrypted in your instance and is injected at execution time.