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.

Quickstart

Get started with Files in minutes using your preferred integration method.

# Add to your MCP client config (Claude Desktop, Cursor, Windsurf)
{
  "jentic": {
    "url": "https://api.jentic.com/mcp",
    "auth": "oauth"
  }
}

# Then ask your agent:
"upload file to hubspot"

# → Jentic returns the GET /events tool with parameter schema, agent executes.

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

GET STARTED

Start building with Files API

Explore with Jentic

View OpenAPI Document

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.

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

Complementary

Marketing Emails

Reference uploaded files by id in marketing email content blocks

Choose this when the file needs to render inside a marketing email.

Complementary

CMS Pages

Reference uploaded files in CMS page content modules

Choose this when the file is a hero image or download for a CMS landing page.

Alternative

Cloudinary Upload API

Dedicated media upload and CDN with richer image processing than HubSpot's file manager

Choose Cloudinary when the use case needs on-the-fly transformations beyond HubSpot's derivative sizes.

Complementary

CMS Media Bridge

Bridge external media providers into HubSpot file references

Choose this when assets live in a third-party DAM and need to be exposed as HubSpot files.

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.