Complete REST API reference for integrating ephemeral text sharing into your applications
Get started with the ZeroHost API in under 5 minutes:
# Create a share
curl -X POST https://api.zerohost.net/v1/share \
-H "Content-Type: application/json" \
-H "X-API-Key: zh_your_api_key_here" \
-d '{
"text": "Hello, World!",
"expires_in": "24h",
"reference": "CLI-001"
}'
# Get a share
curl -H "X-API-Key: zh_your_api_key_here" \
https://api.zerohost.net/v1/share/abc123// Create a share
const response = await fetch('https://api.zerohost.net/v1/share', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-API-Key': 'zh_your_api_key_here'
},
body: JSON.stringify({
text: 'Hello, World!',
expires_in: '24h',
reference: 'JS-001'
})
});
const share = await response.json();
console.log('Share URL:', share.url);import requests
# Create a share
response = requests.post(
'https://api.zerohost.net/v1/share',
headers={
'Content-Type': 'application/json',
'X-API-Key': 'zh_your_api_key_here'
},
json={
'text': 'Hello, World!',
'expires_in': '24h',
'reference': 'PY-001'
}
)
share = response.json()
print(f"Share URL: {share['url']}")The ZeroHost API requires authentication via API keys. API keys provide secure access with higher rate limits and extended features exclusively for DEVELOPER plan users.
All API requests require your API key in the X-API-Key header:
X-API-Key: zh_your_api_key_hereGenerate your API key from your account dashboard:
# All API requests require authentication
curl -H "X-API-Key: zh_your_api_key_here" \
https://api.zerohost.net/v1/share/abc123Create a new ephemeral text share
| Parameter | Type | Required | Description |
|---|---|---|---|
text |
string | Required | Content to share (max 1MB) |
expires_in |
string | Optional | Expiry time: "1h", "6h", "24h", "7d" (default: "24h") |
password |
string | Optional | Password protect the share |
burn_after_reading |
boolean | Optional | Delete after first view (default: false) |
reference |
string | Optional | Reference label (auto-truncated to 8 chars, e.g., "PROJ-123") - authenticated users only |
| Header | Required | Description |
|---|---|---|
Content-Type |
Required | application/json |
X-API-Key |
Required | Your ZeroHost API key (starts with zh_) |
{
"text": "This is my secure content",
"expires_in": "24h",
"password": "mysecretpass",
"burn_after_reading": false,
"reference": "PROJ-123"
}Note: Reference values longer than 8 characters are automatically truncated to the first 8 characters.
{
"id": "9b042e2b144afeb6421592fc7f5c0d94",
"url": "https://zerohost.net/share/9b042e2b144afeb6421592fc7f5c0d94",
"expires_at": "2024-12-16T12:00:00.000Z",
"expires_in": 86400,
"plan": "free",
"usage": {
"current": 3,
"limit": 25
}
}Retrieve a shared text (public shares only)
| Parameter | Type | Description |
|---|---|---|
id |
string | Share ID (32-character hex string) |
{
"id": "9b042e2b144afeb6421592fc7f5c0d94",
"text": "This is my secure content",
"created_at": "2024-12-15T12:00:00.000Z",
"expires_at": "2024-12-16T12:00:00.000Z",
"has_password": false,
"burn_after_reading": false,
"view_count": 1
}{
"error": "Password required",
"message": "This share requires a password",
"requires_password": true
}Retrieve a password-protected share
| Parameter | Type | Description |
|---|---|---|
id |
string | Share ID (32-character hex string) |
| Parameter | Type | Required | Description |
|---|---|---|---|
password |
string | Required | Password for the protected share |
{
"password": "mysecretpass"
}{
"id": "9b042e2b144afeb6421592fc7f5c0d94",
"text": "This is my password-protected content",
"created_at": "2024-12-15T12:00:00.000Z",
"expires_at": "2024-12-16T12:00:00.000Z",
"has_password": true,
"burn_after_reading": false,
"view_count": 1
}Check current usage and limits
| Header | Required | Description |
|---|---|---|
X-API-Key |
Required | Your ZeroHost API key for usage tracking |
{
"plan": "free",
"usage": {
"current": 5,
"limit": 25,
"period": "daily",
"resets_at": "2024-12-16T00:00:00.000Z"
}
}All API errors return JSON with error details:
| Status Code | Error Type | Description |
|---|---|---|
| 400 | Bad Request | Invalid request body or parameters |
| 401 | Unauthorized | Invalid password or authentication required |
| 404 | Not Found | Share not found, expired, or deleted |
| 429 | Rate Limited | Usage limit exceeded |
| 500 | Server Error | Internal server error |
{
"error": "Rate limit exceeded",
"message": "You have reached your daily limit of 25 shares. Upgrade to Pro for unlimited shares.",
"code": "RATE_LIMIT_EXCEEDED",
"details": {
"limit": 25,
"current": 25,
"resets_at": "2024-12-16T00:00:00.000Z"
}
}const ZeroHost = require('zerohost-sdk');
const client = new ZeroHost({
apiKey: 'zh_your_api_key_here'
});
// Create a share
const share = await client.createShare({
text: 'Hello, World!',
expiresIn: '24h',
password: 'optional-password'
});
console.log('Share URL:', share.url);
// Get a share
const content = await client.getShare(share.id, 'optional-password');
console.log('Content:', content.text);from zerohost import ZeroHost
client = ZeroHost(api_key="zh_your_api_key_here")
# Create a share
share = client.create_share(
text="Hello, World!",
expires_in="24h",
password="optional-password"
)
print(f"Share URL: {share.url}")
# Get a share
content = client.get_share(share.id, password="optional-password")
print(f"Content: {content.text}")