.png)
Hugging Face Integration Guide
Connect Hugging Face Hub repositories and inference services with enterprise systems through REST APIs, selected webhooks, and Martini workflows.
Hugging Face integration options at a glance
Hugging Face provides documented REST APIs for Models, Datasets, Spaces, repositories, revisions, files, commits, and inference services. Selected Hub events can be delivered through webhooks configured for repositories, organizations, or account activity, depending on supported scope. Repository files can be uploaded, downloaded, updated, or deleted, with large objects potentially managed through Git LFS. Authentication uses User Access Tokens, including read, write, and fine-grained permissions. Martini can consume these APIs, receive supported webhook notifications, schedule synchronization workflows, transform JSON and file data, and expose controlled APIs that orchestrate Hugging Face operations.
| Integration point | Supported by Hugging Face? | Common use cases | How Martini supports it |
|---|---|---|---|
| REST APIs | Yes | Use Hugging Face Hub and inference APIs to search Models, Datasets, and Spaces; retrieve repository metadata and files; create commits; manage revisions; and call hosted inference services. | Martini can consume documented HTTP APIs, map request and response payloads, apply validation and business rules, and expose an API façade for internal consumers. |
| Webhooks / outbound callbacks | Yes | Hugging Face supports webhook notifications for selected Hub events and scopes, including applicable repository, organization, or account activity. | Martini can expose a webhook endpoint, validate the notification, retrieve the authoritative resource through the REST API, and start a workflow. Coverage remains event- and scope-specific. |
| Bulk / async / batch APIs | Limited | Repository and large-file operations are supported, while asynchronous or batch inference depends on the selected Hugging Face inference product and configuration. | Martini can use asynchronous workflow patterns, bounded polling, checkpoints, and status handling when the selected Hugging Face service exposes a suitable operation model. |
| File / attachment APIs | Yes | Models, Datasets, and Spaces contain repository files that can be uploaded, downloaded, updated, or deleted through Hub mechanisms. Large objects may use Git LFS. | Martini can transfer and transform files, map repository paths, preserve revision metadata, and coordinate staged or retryable processing for large objects. |
| Authentication | Yes | Hugging Face uses User Access Tokens, including read, write, and fine-grained tokens, for authenticated Hub and inference operations. OAuth and delegated authorization are also available for applications. | Martini can store tokens as secrets and inject the least-privileged token into the HTTP Authorization header at runtime. |
| Git and repository revisions | Yes | Repositories use branches, tags, commits, and revisions to identify states of Models, Datasets, and Spaces and to support repeatable publication and retrieval. | Martini can persist commit identifiers, apply deterministic paths, validate revisions, and use revision keys for idempotency and auditability. |
| GraphQL APIs | Not confirmed | No stable, public general-purpose Hugging Face GraphQL integration surface was confirmed. | Martini supports GraphQL consumption generally, but Hugging Face integrations should use the documented REST APIs rather than undocumented GraphQL endpoints. |
| SOAP APIs | No | No Hugging Face SOAP API is confirmed; the documented integration surface is centered on REST, Hub repositories, webhooks, and inference services. | Martini can consume SOAP services from other systems when required in a broader workflow, but SOAP is not an identified Hugging Face integration method. |
| Database / analytics access | No | Hugging Face does not expose a general-purpose customer database interface for direct integration. | Martini can obtain metadata or analytics through applicable APIs, repository files, dataset exports, or a separate database and analytics platform. |
How Hugging Face exposes data and business events
Hugging Face REST APIs
Hugging Face documents HTTP APIs for Hub resources, repositories, Models, Datasets, Spaces, files, commits, revisions, and inference services. These APIs are the primary integration surface for enterprise data exchange and automation.
Martini implementation pattern
Martini implementation pattern: a workflow sends authenticated HTTP requests to the applicable Hugging Face API, validates status and response structure, maps JSON payloads into an internal model, applies business rules, and writes the result to a target system or returns it through a Martini API.
Implementation sequence
Hugging Face Webhooks
Hugging Face supports webhooks for selected Hub events and scopes. Notifications may relate to repository, organization, or account activity, but event coverage is not universal across every resource or action.
Martini implementation pattern
Martini implementation pattern: expose a controlled webhook endpoint, validate the configured secret or signature where provided, inspect the event, retrieve the authoritative resource through the Hugging Face API, and continue processing asynchronously when appropriate.
Implementation sequence
Hugging Face Repository Files
Models, Datasets, and Spaces are repositories containing files that can be uploaded, downloaded, updated, or deleted through Hub mechanisms. Large files may be managed through Git LFS and require careful transfer handling.
Martini implementation pattern
Martini implementation pattern: stage or stream the source file where supported, validate its path and content, invoke the repository or commit API, capture the resulting commit or revision, and retry transient transfer failures without creating duplicate commits.
Implementation sequence
Hugging Face Inference Services
Hugging Face provides hosted inference options, including Inference Endpoints. Response formats, loading behavior, limits, and asynchronous capabilities depend on the selected model, provider, endpoint, and service configuration.
Martini implementation pattern
Martini implementation pattern: expose a normalized internal API, authorize the caller, validate the request, invoke the selected Hugging Face inference service, normalize the model-specific response, and return or persist the result with timeout and failure handling.
Implementation sequence
Common Hugging Face integration patterns
Pattern 1: Promote models through deployment approval
When to use this pattern
Use this pattern when a Model repository change should trigger controlled validation and deployment. It combines selected Hugging Face webhook events with revision-aware retrieval, approval rules, and a deployment API or platform.
Integration direction
Example Mapping
| Hugging Face Field | Canonical Field | Target Field |
|---|---|---|
| repository.id | modelRepositoryId | deployment.modelRepository |
| commit_id | sourceRevision | deployment.revision |
| metadata.pipeline_tag | modelType | deployment.modelType |
| webhook.event | publicationEvent | deployment.trigger |
Martini implementation pattern
Martini receives the supported event, validates its scope and authenticity, retrieves the referenced commit and files, checks required metadata and approval status, then calls the deployment platform. The workflow records the revision as an idempotency key and routes transient failures to bounded retries or operational review.
Martini capabilities used
- workflows
- webhook consumption
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Synchronize Datasets to a data platform
When to use this pattern
Use this pattern when enterprise teams need curated Hugging Face Dataset files or metadata in a data lake, warehouse, or internal database. Scheduling is useful when webhook coverage is insufficient or incremental polling is required.
Integration direction
Example Mapping
| Hugging Face Field | Canonical Field | Target Field |
|---|---|---|
| dataset.id | datasetRepositoryId | source.dataset |
| revision | sourceRevision | ingestion.revision |
| file.path | sourceFilePath | ingestion.filePath |
| file.content | datasetPayload | target.data |
Martini implementation pattern
A scheduler-triggered workflow lists changed revisions, retrieves only required files, validates schema and size, transforms the content, and writes it to the target platform. Martini stores the last processed commit or revision, avoids repeated polling of unchanged resources, and retries rate-limit or transfer failures with backoff.
Martini capabilities used
- scheduled workflows
- API consumption
- file handling
- data mapping
- validation
- checkpointing
- error handling
Pattern 3: Publish approved artifacts to Hugging Face
When to use this pattern
Use this pattern when an internal engineering, data, or ML system needs to publish approved files, evaluation results, or documentation to a Hugging Face Model or Dataset repository.
Integration direction
Example Mapping
| Hugging Face Field | Canonical Field | Target Field |
|---|---|---|
| artifact.name | artifactName | repository.filePath |
| artifact.version | releaseVersion | repository.revision |
| evaluation.status | approvalStatus | publication.approval |
| artifact.content | fileContent | commit.file |
Martini implementation pattern
Martini receives an approved artifact or retrieves it from the source platform, validates release status and deterministic repository paths, then calls the Hugging Face upload or commit API with a write-capable secret. The workflow captures the resulting commit and prevents duplicate publication for the same artifact version.
Martini capabilities used
- workflows
- API consumption
- file processing
- mapping and transformation
- validation
- idempotency
- secrets management
Pattern 4: Expose an inference façade API
When to use this pattern
Use this pattern when internal applications need a stable enterprise API instead of direct dependency on model-specific Hugging Face inference formats, authentication, or endpoint behavior.
Integration direction
Example Mapping
| Hugging Face Field | Canonical Field | Target Field |
|---|---|---|
| request.text | inferenceInput | inputs |
| request.model | modelIdentifier | endpoint.model |
| response.generated_text | generatedOutput | application.result |
| response.error | inferenceError | application.error |
Martini implementation pattern
Martini exposes a REST API, authenticates and authorizes callers, validates the request, selects the permitted Hugging Face endpoint, and normalizes the response. It handles model loading, payload limits, timeouts, provider-specific errors, and asynchronous completion where supported without exposing vendor-specific details to every consumer.
Martini capabilities used
- API exposure
- API consumption
- authentication and authorization
- data transformation
- business rules
- error handling
- asynchronous workflows
Applications commonly integrated with Hugging Face
Hugging Face can be integrated with engineering, storage, data, and machine-learning platforms when organizations need controlled movement of source code, datasets, model artifacts, evaluation results, or inference requests. Martini can mediate these exchanges through APIs, scheduled workflows, webhook processing, validation, transformation, and reusable business rules.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| GitHub | Synchronize source code, model cards, evaluation scripts, or CI/CD events with Hugging Face repositories. | GitHub → Martini → Hugging Face | Martini receives a GitHub event or runs on a schedule, validates the repository and revision, transforms approved files or metadata, and commits selected content to a Hugging Face repository with retry and duplicate protection. |
| GitLab | Move approved model artifacts or Dataset files between GitLab-based engineering workflows and Hugging Face repositories. | GitLab → Martini → Hugging Face | A Martini workflow retrieves approved GitLab artifacts, validates file paths and release status, then uses Hugging Face repository APIs to create a controlled commit and records the resulting revision. |
| Amazon S3 | Stage large training datasets, model artifacts, evaluation outputs, or backups outside the Hugging Face Hub. | Amazon S3 → Martini → Hugging Face | Martini reads approved objects from S3, applies naming and content rules, and uploads selected files to a Hugging Face Dataset or Model repository while accounting for large files and transfer failures. |
| Microsoft Azure Blob Storage | Synchronize enterprise data and model artifacts between Azure storage and Hugging Face repositories or inference workflows. | Microsoft Azure Blob Storage → Martini → Hugging Face | A scheduled or event-driven Martini workflow discovers changed blobs, maps them to deterministic repository paths, and commits them to Hugging Face after validation and authorization checks. |
| Google Cloud Storage | Transfer datasets, model outputs, or evaluation files between Google Cloud storage and Hugging Face. | Google Cloud Storage → Martini → Hugging Face | Martini retrieves selected objects through the storage API, transforms metadata and content as required, and publishes or retrieves repository files using Hugging Face Hub APIs. |
| Databricks | Publish curated datasets or model evaluation results to Hugging Face, or bring Hugging Face assets into machine-learning pipelines. | Databricks → Martini → Hugging Face | Martini orchestrates an export from Databricks, validates dataset status and schema, and writes versioned files to a Hugging Face Dataset repository, retaining the source revision and processing status. |
| Weights & Biases | Synchronize experiment metadata, evaluation outputs, and model publication processes. | Weights & Biases → Martini → Hugging Face | Martini consumes approved experiment or evaluation data, applies publication rules, and coordinates repository updates or downstream notifications without assuming undocumented product events. |
| MLflow | Coordinate model registry, evaluation, and publication workflows between MLflow and Hugging Face repositories or inference deployments. | MLflow → Martini → Hugging Face | A Martini workflow retrieves an approved MLflow model or evaluation result, checks release conditions, maps metadata to Hugging Face repository conventions, and publishes a revision or starts deployment orchestration. |
How to build a Hugging Face integration in Martini
Objective
Establish authenticated access to the required Hugging Face Hub or inference APIs using a token with only the permissions needed by the workflow.
Instructions in Martini
- Create a Martini secret for the Hugging Face User Access Token.
- Inject the token into the HTTP Authorization header at runtime.
- Choose read, write, or fine-grained permissions according to the operation.
- Store repository, organization, endpoint, and environment configuration separately from workflow logic.
Objective
Select the trigger that matches the required freshness and event coverage: a supported Hugging Face webhook, an API request, or a scheduled synchronization.
Instructions in Martini
- Use a webhook-triggered workflow for supported Hub events.
- Use a scheduler when webhook coverage is insufficient or periodic reconciliation is required.
- Expose a Martini REST API when applications need a controlled request or inference façade.
- Define an idempotency key using an event identifier, commit hash, or revision.
Objective
Obtain the authoritative resource, revision, file, or inference response from Hugging Face rather than relying solely on notification payloads.
Instructions in Martini
- Call the applicable Hub, repository, file, or inference endpoint.
- Follow pagination for list operations.
- Retrieve the referenced commit or revision for reproducibility.
- Stage or stream large files carefully and account for Git LFS behavior.
Objective
Coordinate validation, enrichment, transformation, target writes, notifications, and asynchronous work as a maintainable Martini workflow.
Instructions in Martini
- Separate event receipt from longer-running processing when necessary.
- Apply repository, organization, model, dataset, and endpoint authorization rules.
- Use reusable workflow logic for common Hugging Face operations.
- Persist checkpoints, source revisions, and processing status.
Objective
Convert Hugging Face JSON, repository metadata, file content, and inference responses into the canonical model expected by downstream systems.
Instructions in Martini
- Map Models, Datasets, Spaces, revisions, files, and inference results explicitly.
- Validate required fields and preserve unknown metadata where appropriate.
- Normalize model- or provider-specific inference responses.
- Version mappings when payload structures materially change.
Objective
Enforce publication, approval, content, data-quality, and deployment policies before changing repositories or downstream systems.
Instructions in Martini
- Check approval status and permitted repository paths.
- Reject unexpected webhook scopes or unauthorized identifiers.
- Use deterministic file paths and content checks to prevent duplicate commits.
- Record the source revision and decision outcome for auditability.
Common Hugging Face data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Models | Versioned model repositories containing weights, configuration, metadata, and documentation used for publication, retrieval, evaluation, or inference. | MLflow, Databricks, cloud storage, deployment platforms, internal model catalogs | Martini retrieves metadata and revisions, validates release rules, maps model information, and orchestrates publication or deployment workflows. |
| Datasets | Dataset repositories containing files, metadata, dataset cards, and revisions for training, evaluation, and controlled data exchange. | Amazon S3, Databricks, data warehouses, internal databases, data lakes | Martini can retrieve or publish Dataset files, transform content, preserve revision identifiers, and process incremental changes through scheduled or webhook-triggered workflows. |
| Spaces | Hosted machine-learning applications commonly implemented with Gradio or Streamlit. | deployment platforms, internal application catalogs, monitoring and approval systems | Martini can retrieve Space metadata and selected repository files, apply approval rules, and notify or orchestrate downstream processes. |
| Repositories and revisions | Git-backed resources and branches, tags, or commits that identify a precise state of a Model, Dataset, or Space. | GitHub, GitLab, release systems, deployment platforms, audit stores | Martini stores commit or revision identifiers, uses them as checkpoints and idempotency keys, and validates source state before downstream actions. |
| Files and LFS objects | Configuration files, tokenizer files, model weights, dataset files, evaluation outputs, and other repository content, including large Git LFS objects. | Amazon S3, Azure Blob Storage, Google Cloud Storage, data platforms, deployment systems | Martini transfers files through repository APIs, applies path and content rules, and accounts for streaming, timeouts, partial transfers, and large-object processing. |
| Inference Endpoints | Dedicated hosted deployments that expose models for inference requests and responses. | internal applications, API gateways, workflow systems, monitoring platforms | Martini can expose a controlled façade, call the inference service, normalize provider- or model-specific responses, and handle timeouts or asynchronous completion where supported. |
Authentication and security considerations
Token-based authentication
Hugging Face APIs use User Access Tokens in the HTTP Authorization header. Read, write, and fine-grained tokens support different levels of access to repositories and resources.
Least-privilege secrets
Store Hugging Face tokens in Martini secrets management rather than embedding them in workflows or API definitions. Use read-only or fine-grained permissions when write access is unnecessary.
Webhook protection
Webhook workflows should validate configured secrets or signatures where provided, reject unexpected methods and scopes, and authorize repository or organization identifiers before processing the event.
Controlled API exposure
When Martini exposes an inference or repository façade, apply authentication and authorization to the Martini API and avoid exposing Hugging Face tokens to consuming applications.
Operational considerations for Hugging Face integrations
Rate limits and retries
Hugging Face APIs and inference services may apply rate limits, quotas, or usage restrictions. Handle HTTP 429 responses, respect retry information when available, and use bounded backoff instead of repeated immediate polling.
Pagination and checkpoints
List operations may be paginated. Persist continuation state, commit identifiers, or revisions so scheduled workflows can process incrementally and repeatably.
Large files and Git LFS
Model weights and datasets can be large. Account for Git LFS, memory consumption, timeouts, staged or streaming transfers, partial-transfer recovery, storage, and egress costs.
Idempotency and schema changes
Use event IDs, commit hashes, revisions, deterministic paths, and content checks to prevent duplicate processing. Validate required fields, preserve appropriate unknown fields, and version mappings when model metadata or inference responses change.
Testing and observability
Test representative repository, webhook, file, and inference payloads. Monitor workflow logs, response status, revision checkpoints, retry counts, transfer results, and asynchronous operation status.
Why use Martini instead of scripts or point-to-point integrations?
Orchestration beyond a script
Martini coordinates Hugging Face API calls, webhook receipt, scheduled synchronization, file processing, downstream writes, business rules, and asynchronous work in maintainable workflows.
Reusable API assets
Martini can expose controlled REST APIs that abstract Hugging Face authentication, endpoint selection, repository rules, and model-specific inference response formats from consuming applications.
Reliable data movement
Mapping, validation, checkpoints, idempotency, bounded retries, and operational logging provide a more controlled approach than isolated scripts or tightly coupled point-to-point integrations.
Flexible enterprise connectivity
Martini can combine Hugging Face REST and webhook integration with databases, files, storage services, messaging, and other enterprise APIs in the same workflow, while retaining secure environment configuration.
Frequently asked questions
Hugging Face can be integrated through its documented REST APIs for Models, Datasets, Spaces, repositories, files, revisions, commits, and inference services. Selected Hub events can be delivered through webhooks, while scheduled workflows can support reconciliation and synchronization where event coverage is insufficient.
Yes. Martini can consume Hugging Face REST APIs, receive supported Hugging Face webhook events, transfer repository files, call inference services, transform payloads, and expose controlled APIs that orchestrate Hugging Face operations.
No. A dedicated Hugging Face connector is not required. Martini can integrate using Hugging Face REST APIs, supported webhooks, repository and file mechanisms, User Access Tokens, and the applicable inference endpoints.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Hugging Face. Integrations are subject to the provisioned capacity of the Martini environment. Separate costs may apply from Hugging Face, cloud infrastructure, storage, inference usage, or other third-party systems.
Use the documented Hugging Face Hub REST APIs for Models, Datasets, Spaces, repositories, files, commits, and revisions, together with the applicable inference API or Inference Endpoint interface. Use webhooks for supported Hub events and scheduled synchronization when webhook coverage does not meet the requirement. A stable general-purpose GraphQL API and a SOAP API were not confirmed.
Yes. Martini can expose a webhook endpoint and process supported Hugging Face notifications for configured repository, organization, or account scopes. Event coverage is limited to the event types and scopes documented by Hugging Face, so workflows should retrieve the authoritative resource through the API after validating the notification.
A scheduled or webhook-triggered Martini workflow can retrieve Dataset files, Model metadata, repository revisions, or inference results, map them into a canonical structure, apply validation and business rules, and write them to a database, data platform, deployment service, or another API. Commit identifiers and revisions can provide checkpoints and idempotency keys.
Martini workflows can handle rate limits, transient HTTP failures, timeouts, incomplete transfers, and inference errors with bounded retries, backoff, validation, and operational logging. Event IDs, commit hashes, revisions, deterministic paths, and content checks help prevent duplicate processing. Long-running inference should use asynchronous workflow patterns when supported by the selected Hugging Face service.
Related Martini documentation
APIs
Operations
Connect Hugging Face to your enterprise workflows
Use Martini to integrate Hugging Face APIs, selected webhooks, repository files, and inference services with the applications and data platforms your organization already operates.