Files

Name: Files API
Brand: Files
Availability: InStock

★ 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.

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.

Install Jentic One Beta (Self-Hosted)

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 | sh

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 instance

Jentic 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

GET STARTED

Start building with Files API

Explore with Jentic

View OpenAPI Document

Jentic publishes the only available OpenAPI document for Files, keeping it validated and agent-ready.

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.

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

Why though 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.

Complementary

HubSpot CMS Domains

CMS Domains determines the hostname that serves files uploaded via the Files API

Use the Files API to host an asset; use CMS Domains to confirm which hostname will deliver the file.

Complementary

HubSpot Marketing Events Extension

Marketing materials hosted on Files are referenced inside marketing event records

Use the Files API to host the asset; use the Marketing API when registering the event that references it.

Alternative

SendGrid

SendGrid handles email delivery — used for transactional sends rather than HubSpot's marketing asset hosting

Pick SendGrid when sending transactional email outside HubSpot; pick HubSpot Files when assets need to live alongside HubSpot CRM and marketing data.

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.