HubSpot Files
Browse all Hubspot APIs✓ Official Vendor SpecStorageObject Storageoauth220 EndpointsREST
For 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.
Use for: I need to upload a PDF to the HubSpot file manager, Import a large image from a public URL into HubSpot asynchronously, Generate a signed URL for a private HubSpot file, Organise marketing assets into a new folder
Not supported: Does not transcode video, perform on-the-fly image transformations, or manage CRM records — use for HubSpot file manager uploads, organisation, and retrieval only.
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.
Install Jentic One Beta
Connect the Files to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Files, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL https://raw.githubusercontent.com/jentic/jentic-one/main/tools/install.sh | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Files API.
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
Patterns agents use Files API for, with concrete tasks.
★ 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.
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.
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.
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.
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
20 endpoints — 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.
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
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
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth and private app tokens are stored encrypted in the Jentic MAXsystem vault. Agents receive scoped execution access — the raw bearer token never enters the agent's context window or logs.
Intent-based discovery
Agents search Jentic with intents like 'upload file to hubspot' and Jentic returns the matching operation with its multipart input schema, so the agent calls POST /files/v3/files with the right body without browsing HubSpot docs.
Time to first call
Direct HubSpot integration: 2-3 days for OAuth setup, multipart handling, async job polling, and folder management. Through Jentic: under 1 hour — search, load schema, execute.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Files API through Jentic.
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 MAXsystem 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. Sign up at https://app.jentic.com/sign-up.
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.
GET STARTED