Agent-ready OpenAPI document · curated by JenticStorageObject Storageoauth2, apiKey18 EndpointsREST
Know of an official OpenAPI document? Contribute it →
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://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-files-api" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fhubapi.com%2Fhubspot-files-api" | 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
Jentic AI Readiness Score
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
F
Files
- Foundational (C-)52/100
72
Foundational Compliance56
Developer Experience & Jentic Compatibility29
AI-Readiness & Agent Experience94
Agent Usability52
Security100
AI DiscoverabilityPowered by JenticScoring Framework 1.0.0 | Scoring Engine 0.4.0
Show dimension breakdown
72
Foundational Compliance
Base layer of spec validity and structural soundness.
Grade: A-Signals: 4
88%
Lint Results
Aggregated quality score from linter diagnostics, weighted by severity.
100%
Resolution Completeness
Percentage of `$ref` references that resolve successfully.
0%
Specification Validity
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
100%
Structural Integrity
Structural correctness score based on schema issues using logarithmic dampening.
56
Developer Experience & Jentic Compatibility
Clarity, completeness, and ingestion readiness for developers and tooling.
Grade: CSignals: 4
2%
Example Density
How richly the API is illustrated with examples.
71%
Example Validity
Percentage of examples that conform to their schemas.
50%
Response Coverage
Percentage of operations with complete response definitions (success, client error, server error).
100%
Tooling Readiness
Health of API ingestion, bundling, and resolution within Jentic pipelines.
29
AI-Readiness & Agent Experience
Semantic breadth, depth, and agent comprehension for AI systems.
Grade: FSignals: 4
58%
Description Coverage
Coverage of descriptions across API elements.
0%
Error Standardization
Coverage of RFC 9457 Problem Details for error responses.
0%
OperationId Quality
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
58%
Summary Coverage
Coverage of summaries across operations/tags/info.
94
Agent Usability
Functional utility, complexity comfort, and AI orchestration readiness.
Grade: A+Signals: 1
94%
Complexity Comfort
Agent comfort level based on API operational and structural complexity.
52
Security
Trust, risk posture, and security compliance.
Grade: C-Signals: 1
52%
Authentication Strength
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
100
AI Discoverability
Findability, semantic richness, and reasoning readiness.
Grade: A+Signals: 1
100%
Descriptive Richness
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>Why Jentic?
What agents get from Jentic-routed access to this vendor.
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 isolation
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.
Intent-based discovery
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
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 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.
GET STARTED