Publishing to SyftHub

SyftHub is the decentralized marketplace where knowledge providers meet knowledge seekers. Publishing your endpoints to SyftHub makes them discoverable, allows others to query your data, and connects you to the broader Syft network. This guide shows you how to publish and manage your endpoints on SyftHub.

Understanding SyftHub

SyftHub acts as a registry and discovery layer for Syft Space endpoints: For providers (you):

Publish endpoints to reach a wider audience
Control access through policies
Track usage and analytics
Monetize your knowledge

For consumers:

Discover endpoints across the network
Query multiple Spaces through a unified interface
Pay for access to premium knowledge
Build applications on top of distributed knowledge

Publishing to SyftHub doesn’t give others access to your raw data. They can only query through your endpoint’s API, subject to your policies.

Prerequisites

Before publishing, ensure you have:

Working endpoint

Your endpoint must be:

Fully configured with dataset and/or model

Tested and verified to work correctly

Set to published: true status

Policies configured

Add appropriate policies:

Access policy - Control who can query (recommended)

Rate limit policy - Prevent abuse (recommended)

Accounting policy - Track costs or require payment (optional)

Network connectivity

For local deployments:

Developer token - Required to publish from localhost

Configured in Settings → Network
Contact OpenMined to obtain token during beta

For cloud/VM deployments:

Public IP address - Automatically detected

No developer token needed

Marketplace connection

Your Syft Space must be connected to at least one marketplace:

Default: SyftHub (syfthub.openmined.org)

Additional marketplaces can be added in Settings

Publishing an endpoint

Navigate to endpoint

Click on the endpoint you want to publish.

Review endpoint details

Verify your endpoint is ready:

Name and description are clear and informative

Tags accurately describe the content

Dataset and model are healthy

Policies are configured appropriately

Check slug availability

Before publishing, verify your slug isn’t already taken:

Click Check Availability on the endpoint detail page

Review availability across all marketplaces

If taken, choose a different slug and update your endpoint

Slug conflicts will cause publishing to fail. Always check availability first.

Choose marketplaces

Decide where to publish:

Option 1: Publish to all marketplaces

{
  "publish_to_all_marketplaces": true
}

Option 2: Publish to specific marketplaces

{
  "marketplace_ids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "223e4567-e89b-12d3-a456-426614174000"
  ],
  "publish_to_all_marketplaces": false
}

Publish endpoint

Click Publish to SyftHub and select your marketplaces.

Review results

The publish operation returns results for each marketplace:

{
  "endpoint_slug": "research-qa",
  "results": [
    {
      "marketplace_id": "...",
      "marketplace_name": "SyftHub",
      "success": true,
      "message": "Successfully published endpoint",
      "error": null
    }
  ]
}

Publishing via API

You can also publish endpoints programmatically: Endpoint: POST /api/v1/endpoints/{slug}/publish Headers:

Content-Type: application/json
Authorization: Bearer <your-token>

Body (publish to all):

{
  "publish_to_all_marketplaces": true
}

Body (publish to specific):

{
  "marketplace_ids": [
    "123e4567-e89b-12d3-a456-426614174000"
  ],
  "publish_to_all_marketplaces": false
}

cURL example

curl -X POST http://localhost:8080/api/v1/endpoints/research-qa/publish \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-token" \
  -d '{
    "publish_to_all_marketplaces": true
  }'

Python example

import requests

url = "http://localhost:8080/api/v1/endpoints/research-qa/publish"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer your-token"
}
payload = {
    "publish_to_all_marketplaces": True
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

for marketplace_result in result["results"]:
    if marketplace_result["success"]:
        print(f"✓ Published to {marketplace_result['marketplace_name']}")
    else:
        print(f"✗ Failed: {marketplace_result['error']}")

What happens when you publish

When you publish an endpoint to SyftHub:

Registration

Metadata sent - Name, description, tags, response type
Connection info - Your Space’s public URL or developer token
Policy summary - Access requirements, rate limits, pricing
Health check - SyftHub verifies the endpoint is accessible

Discovery

Search indexing - Endpoint becomes searchable on SyftHub
Category listing - Appears in relevant category pages
Tag filtering - Can be found via tag searches
Recommendations - May appear in related endpoint suggestions

Connectivity

Proxy setup - SyftHub routes queries to your Space
Authentication - SyftHub issues satellite tokens for users
Monitoring - Usage and health metrics tracked
Updates - Changes to your endpoint sync to SyftHub

Your endpoint remains under your control. You can unpublish, update, or delete it at any time.

Managing published endpoints

Viewing publication status

Check where your endpoint is published:

Navigate to the endpoint detail page
View the “Published to” section
See status for each marketplace:
- Published and active
- Publication pending
- Publication failed (with error)
- Not published

Updating published endpoints

Changes to your endpoint automatically sync to SyftHub: Automatically synced:

Name changes
Description updates
Tag modifications
Policy changes
Health status

Requires manual action:

Slug changes (must unpublish and republish)
Dataset/model changes (unpublish, update, republish recommended)
Response type changes (unpublish, update, republish recommended)

Metadata syncs within a few minutes. Allow time for changes to propagate before testing.

Unpublishing endpoints

Remove your endpoint from SyftHub:

Navigate to endpoint

Click on the published endpoint.

Unpublish

Click Unpublish from SyftHub.

Confirm action

Confirm you want to unpublish. This will:

Remove the endpoint from search results

Stop accepting new queries through SyftHub

Invalidate existing satellite tokens for this endpoint

Preserve your local endpoint configuration

Via API:

curl -X POST http://localhost:8080/api/v1/endpoints/research-qa/unpublish \
  -H "Authorization: Bearer your-token"

Unpublishing immediately breaks existing integrations. Notify users before unpublishing production endpoints.

Developer token setup

For local deployments, you need a developer token to publish:

Obtaining a token

During onboarding - Add token when registering your Space
Settings page - Navigate to Settings → Network → Developer Token
Contact OpenMined - Request token during beta period

Configuring the token

Open settings

Navigate to Settings → Network.

Enter token

Paste your developer token in the “Developer Token” field.

Save configuration

Click Save. Your Space validates the token with SyftHub.

Verify connection

Check that the connection status shows “Connected”.

When tokens are needed

Deployment Type	Token Required?	Reason
Local machine (localhost)	Yes	No public IP for SyftHub to reach
Cloud VM with public IP	No	SyftHub can reach directly
Docker on VM	No	Uses VM’s public IP
Local development only	No	Not publishing to SyftHub

Developer tokens are temporary during beta. Production will use automatic tunnel setup.

Marketplace configuration

Manage which marketplaces your Space can publish to:

Viewing marketplaces

Navigate to Settings → Marketplaces to see:

Connected marketplaces
Connection status (active, error, disabled)
Number of endpoints published to each

Adding marketplaces

Click add marketplace

On the Marketplaces settings page, click Add Marketplace.

Enter marketplace details

Name - Display name (e.g., “Custom Hub”)

URL - Marketplace API endpoint

API Key - Authentication credential (if required)

Save and test

Click Save. Your Space tests the connection.

Publish endpoints

New marketplace appears in publish dialogs.

Removing marketplaces

Unpublish all endpoints from the marketplace first
Click Remove on the marketplace settings page
Confirm removal

Removing a marketplace while endpoints are published will leave orphaned listings. Always unpublish first.

Monitoring published endpoints

Usage analytics

Track how your published endpoints are being used: Per-endpoint metrics:

Total queries over time
Unique users querying
Geographic distribution
Peak usage times
Average query cost

Policy enforcement:

Access denials (403 errors)
Rate limit hits (429 errors)
Failed queries (400/500 errors)
Successful queries (200 responses)

Health monitoring

SyftHub periodically checks your endpoint health:

Every 5 minutes (default interval)
After receiving error reports from users
When you update the endpoint

Health statuses:

Healthy - Endpoint responding normally
Degraded - Elevated error rates
Unhealthy - Failing health checks
Offline - Unable to reach endpoint

Endpoints marked “Unhealthy” or “Offline” are deprioritized in search results until health is restored.

User feedback

Monitor feedback from SyftHub users:

Ratings (if enabled)
Usage frequency
Error reports
Feature requests

Troubleshooting publication

Publication fails

Symptom: Publish operation returns errors Common causes:

Slug conflict
- Another endpoint already uses this slug
- Solution: Check slug availability and choose a unique one
Network unreachable
- SyftHub cannot reach your Space
- Solution (local): Add/verify developer token
- Solution (VM): Check firewall rules and public IP
Authentication failed
- Invalid developer token or credentials
- Solution: Verify token in Settings → Network
Endpoint unhealthy
- Dataset or model not responding
- Solution: Test connection on endpoint detail page

Queries fail after publishing

Symptom: Users receive errors when querying Common causes:

Policies too restrictive
- Access policy blocks legitimate users
- Solution: Review and adjust access patterns
Rate limits exceeded
- Unexpected query volume
- Solution: Increase rate limits or add user tiers
Backend issues
- Dataset or model becomes unhealthy
- Solution: Check provisioner status and health checks
Satellite token issues
- SyftHub authentication failing
- Solution: Verify marketplace connection in settings

Endpoint not appearing in search

Symptom: Users can’t find your endpoint on SyftHub Solutions:

Wait for indexing - Allow 5-10 minutes after publishing
Check health status - Unhealthy endpoints are deprioritized
Improve metadata - Add relevant tags and clear description
Verify publication - Check endpoint detail page shows “Published”

Best practices

Before publishing

Test thoroughly - Verify endpoint works with various queries
Set up policies - Don’t publish without access control and rate limits
Write clear descriptions - Help users understand what your endpoint offers
Choose relevant tags - Improve discoverability with accurate tags
Check slug availability - Avoid conflicts before publishing

After publishing

Monitor health - Set up alerts for health status changes
Track usage - Watch for unusual patterns or abuse
Respond to issues - Fix problems quickly to maintain reputation
Update regularly - Keep descriptions and tags current
Gather feedback - Learn from how users interact with your endpoint

Maintenance

Schedule updates - Announce maintenance windows to users
Test before deploying - Use unpublished test endpoints
Version carefully - Breaking changes may require new endpoints
Document changes - Keep description updated with new features
Monitor post-update - Watch for issues after changes

Security

Use access policies - Don’t publish completely open endpoints
Implement rate limits - Protect against abuse
Monitor queries - Look for adversarial or malicious patterns
Rotate credentials - Update API keys regularly
Review policies - Adjust based on actual usage patterns

Understanding the Syft network

Decentralized architecture

The Syft network is designed for autonomy:

No central authority - Each Space is independent
Open protocol - Anyone can create marketplaces
Direct connections - Queries route directly to your Space
Local control - You manage your data and policies

Multiple marketplaces

You can publish to multiple marketplaces simultaneously:

General purpose - SyftHub for broad discovery
Industry specific - Vertical marketplaces (healthcare, legal, etc.)
Private networks - Organization-specific registries
Regional - Geographic or language-focused marketplaces

Attribution and tracking

The network maintains attribution:

Query origin - Every query includes verified user identity
Usage tracking - Automatic accounting across network
Citation - Source endpoints credited in responses
Reputation - Reliability and quality tracked over time

Next steps

Query endpoints

Learn how users will query your published endpoints

Monitor usage

Track analytics and performance for your published endpoints

Get Started

Core Concepts

Guides

Desktop App

Deployment

Advanced

​Understanding SyftHub

​Prerequisites

​Publishing an endpoint

​Publishing via API

​cURL example

​Python example

​What happens when you publish

​Registration

​Discovery

​Connectivity

​Managing published endpoints

​Viewing publication status

​Updating published endpoints

​Unpublishing endpoints

​Developer token setup

​Obtaining a token

​Configuring the token

​When tokens are needed

​Marketplace configuration

​Viewing marketplaces

​Adding marketplaces

​Removing marketplaces

​Monitoring published endpoints

​Usage analytics

​Health monitoring

​User feedback

​Troubleshooting publication

​Publication fails

​Queries fail after publishing

​Endpoint not appearing in search

​Best practices

​Before publishing

​After publishing

​Maintenance

​Security

​Understanding the Syft network

​Decentralized architecture

​Multiple marketplaces

​Attribution and tracking

​Next steps

Query endpoints

Monitor usage

Build docs developers (and LLMs) love

Understanding SyftHub

Prerequisites

Publishing an endpoint

Publishing via API

cURL example

Python example

What happens when you publish

Registration

Discovery

Connectivity

Managing published endpoints

Viewing publication status

Updating published endpoints

Unpublishing endpoints

Developer token setup

Obtaining a token

Configuring the token

When tokens are needed

Marketplace configuration

Viewing marketplaces

Adding marketplaces

Removing marketplaces

Monitoring published endpoints

Usage analytics

Health monitoring

User feedback

Troubleshooting publication

Publication fails

Queries fail after publishing

Endpoint not appearing in search

Best practices

Before publishing

After publishing

Maintenance

Security

Understanding the Syft network

Decentralized architecture

Multiple marketplaces

Attribution and tracking

Next steps