HubSpot Files
Browse all Hubapi APIs★ Only Publicly Available OpenAPI DocumentStorageObject Storageoauth2, apiKey18 EndpointsREST
For Agents
Upload, organise, and serve files in HubSpot, including async URL imports, folder management, signed URL generation, and GDPR-compliant deletion.
Use for: I need to upload a file to HubSpot, Import a file from a URL into HubSpot asynchronously, Search for files in HubSpot by name, Generate a signed URL for a HubSpot file
Not supported: Does not handle CRM record attachments at the contact level, image transformations, or video transcoding — use for file storage, retrieval, and folder management only.
Jentic publishes the only available OpenAPI specification for HubSpot Files, keeping it validated and agent-ready. The HubSpot Files API uploads, organises, and serves files used across the HubSpot platform — images embedded in marketing emails, PDFs attached to deals, documents shared in conversations. It supports direct upload, async import-from-URL, signed URL generation, folder management, and GDPR delete. Files and folders can be searched by name, parent path, and access level.
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 to HubSpot with access-level control
Import a file asynchronously from an external URL and poll for status
Search files and folders by name, parent path, and metadata
Generate a signed URL for secure, time-limited file access
GDPR-delete a file to satisfy data subject deletion requests
Manage folders including create, move, search, and async batch updates
Use Cases
Patterns agents use Files API for, with concrete tasks.
★ Marketing Asset Upload Pipeline
Marketing teams upload images, PDFs, and videos used in emails, landing pages, and social posts. The Files API accepts a multipart upload to /files/v3/files with an access-level setting (PUBLIC_INDEXABLE, PUBLIC_NOT_INDEXABLE, or PRIVATE) and returns the hosted URL. The same flow handles batches via async import-from-URL when the source is already on the public web.
Upload product-launch.pdf to folder 'Launches/2026-Q3' with access PUBLIC_NOT_INDEXABLE and return the hosted URL
Signed URL for Private Files
Some files — sales decks, signed contracts, internal reports — must not be publicly accessible. Storing them with access PRIVATE keeps them invisible to anonymous traffic, and the signed-url endpoint returns a time-limited URL when an authorised system needs to share access. The signed URL expires automatically.
Call GET /files/v3/files/{fileId}/signed-url for fileId 99887 with expirationSeconds=3600 and return the signed URL
GDPR Data Subject Deletion
When a contact submits a GDPR delete request, every file that contains their personal data — uploaded resumes, support attachments, ID documents — must be permanently destroyed. The /files/v3/files/{fileId}/gdpr-delete endpoint performs a hard delete that cannot be reversed and is recorded in HubSpot's audit log.
Call DELETE /files/v3/files/{fileId}/gdpr-delete for every fileId associated with the contact's GDPR request
Folder Hierarchy Management
Large portals organise hundreds of thousands of files into structured folder trees. The folders endpoints create, move, search, and update folders; the async folder update task is used for bulk reorganisations that would otherwise time out. Search supports filtering by parent path so a script can walk the tree.
Create folder 'Webinars/2026' under parent path '/Marketing', then move all webinar PDFs from 'Marketing/Old Webinars' into the new folder using the async update endpoint
Agent-Driven Asset Hosting
An AI agent that generates marketing collateral uses Jentic to host the resulting files on HubSpot. It searches for 'upload file to hubspot', loads the schema, and uploads the rendered PDF or image with the appropriate access level. The hosted URL is then embedded in the next email or landing page.
Search Jentic for 'upload file to hubspot', load the schema for POST /files/v3/files, and upload the generated PDF with access PUBLIC_NOT_INDEXABLE
Key Endpoints
18 endpoints — jentic publishes the only available openapi specification for hubspot files, keeping it validated and agent-ready.
METHOD
PATH
DESCRIPTION
POST
/files/v3/files
Upload a file
GET
/files/v3/files/{fileId}
Get a file by ID
POST
/files/v3/files/search
Search files
GET
/files/v3/files/{fileId}/signed-url
Generate a signed URL for a file
DELETE
/files/v3/files/{fileId}/gdpr-delete
GDPR-delete a file
POST
/files/v3/files/import-from-url/async
Import a file asynchronously from a URL
POST
/files/v3/folders
Create a folder
POST
/files/v3/folders/search
Search folders
POST
/files/v3/files
Upload a file
GET
/files/v3/files/{fileId}
Get a file by ID
POST
/files/v3/files/search
Search files
GET
/files/v3/files/{fileId}/signed-url
Generate a signed URL for a file
DELETE
/files/v3/files/{fileId}/gdpr-delete
GDPR-delete a file
POST
/files/v3/files/import-from-url/async
Import a file asynchronously from a URL
POST
/files/v3/folders
Create a folder
POST
/files/v3/folders/search
Search folders
Why Jentic?
Three things that make agents converge on Jentic-routed access.
Credential isolation
HubSpot OAuth tokens, private app tokens, and legacy hapikeys are stored encrypted in the Jentic vault. Agents receive a scoped token at call time so HubSpot credentials never enter the agent's context.
Intent-based discovery
Agents search by intent (e.g., 'upload file to hubspot') and Jentic returns POST /files/v3/files with its multipart schema, including the folderPath, access, and overwrite fields.
Time to first call
Direct HubSpot integration: 1-2 days for OAuth, multipart handling, async task polling, and folder lookup. 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.
Why is there no official OpenAPI spec for HubSpot Files?
HubSpot does not publish an OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call HubSpot Files via structured tooling. It is validated against the live API and kept up to date. Get started at https://app.jentic.com/sign-up.
What authentication does the HubSpot Files API use?
It accepts OAuth 2.0 access tokens, the private-app-legacy header for private apps, and the hapikey query parameter as a legacy fallback. Jentic stores all credential types in its encrypted vault and provides agents with scoped tokens at execution time.
Can I import a file directly from a URL?
Yes. POST /files/v3/files/import-from-url/async returns a taskId, and you poll GET /files/v3/files/import-from-url/async/tasks/{taskId}/status until the task completes. This is the recommended path when the source file is already publicly accessible — it avoids streaming bytes through your own service.
What are the rate limits for the HubSpot Files API?
Standard HubSpot API limits apply: 100 requests per 10 seconds per private app token and 110 per 10 seconds per OAuth app per portal. File size is capped at 100MB per upload, and async URL imports support larger source files within the same per-portal storage quota.
How do I generate a signed URL for a private file through Jentic?
Search Jentic for 'hubspot signed url for file', load the schema for GET /files/v3/files/{fileId}/signed-url, and execute with the fileId and an expirationSeconds value. The response includes a time-limited URL that lets the recipient download the file without HubSpot credentials.
Is the HubSpot Files API free?
API access is included with any HubSpot subscription. Storage quotas and bandwidth allowances scale with the Marketing Hub or CMS Hub tier; check the file usage section of the portal account settings for current limits.
GET STARTED