canonical: https://jentic.com/apis/hubapi.com/hubspot-files-api

# HubSpot Files

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.

## For AI agents

Upload, organise, and serve files in HubSpot, including async URL imports, folder management, signed URL generation, and GDPR-compliant deletion.

## Scope

Does not handle CRM record attachments at the contact level, image transformations, or video transcoding - use for file storage, retrieval, and folder management only.

## Capabilities

- 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

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

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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.

Example prompt: 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

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

## Key resources

- **Files** — Upload, retrieve, search, and delete files including GDPR delete and signed URL generation
- **Folders** — Create, search, and update folders including async batch folder updates
- **Import Tasks** — Asynchronously import files from external URLs and poll for task status

## Why Jentic

- **Setup:** Wiring the HubSpot Files API by hand means handling both OAuth and app-token auth against api.hubapi.com, driving multipart uploads, and following the async import-from-url job yourself. Through Jentic you install once, import Files from the API Directory, store the credential once, and your agent calls it.
- **Permission scoping:** This API mixes file operations that carry the file id in the URL path with uploads and searches that take a request body, so limit the agent to the operations it needs, such as uploading a file or fetching a signed URL. You choose that set, so GDPR delete with DELETE /files/v3/files/{fileId}/gdpr-delete is not included unless you add it.
- **Credential handling:** Your HubSpot credential is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'upload a file to hubspot', and Jentic returns POST /files/v3/files with its multipart schema, including the folderPath, access, and overwrite fields, so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **HubSpot CMS Domains** — CMS Domains determines the hostname that serves files uploaded via the Files API
- **HubSpot Marketing Events Extension** — Marketing materials hosted on Files are referenced inside marketing event records
- **SendGrid** — SendGrid handles email delivery - used for transactional sends rather than HubSpot's marketing asset hosting

## FAQ

### 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 with Jentic One, the self-hosted execution layer.

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

### Can I limit what my agent is allowed to do with the HubSpot Files API?

Yes. Because Jentic One is self-hosted, you decide which HubSpot Files operations your agent can call, so you can allow only what it needs, such as uploading a file with POST /files/v3/files or fetching a signed URL with GET /files/v3/files/{fileId}/signed-url. Destructive operations like DELETE /files/v3/files/{fileId}/gdpr-delete stay off limits unless you explicitly add them, and your HubSpot credential is injected at execution time under your own rules rather than exposed to the agent. The operator, not the agent, controls the exact set of file, folder, and import calls that are permitted.