HubSpot Files

Name: Files API
Brand: Files
Availability: InStock

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

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.

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

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

GET STARTED

Start building with Files API

Explore with Jentic

View OpenAPI Document

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.

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

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.

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.

HubSpot Files

Connect the Files to your agent

Capabilities

Start building with Files API

Use Cases

Key Endpoints

Why Jentic?

Related APIs

FAQs