CORS Proxy

Fetch external APIs from artifact JavaScript without CORS errors. ShareOut proxies the request server-side and forwards the response.

Quick start

const sdk = await ShareOut.create();

// Per-artifact proxy (recommended)
const proxyUrl = `https://shareout.site/v1/data/${sdk.artifactId}/proxy`;
const response = await fetch(`${proxyUrl}?url=${encodeURIComponent('https://api.weather.gov/points/39.7456,-104.9910')}`);
const data = await response.json();

When to use

Scenario	Solution
API without CORS headers	Use the proxy
Public APIs (weather, crypto, etc.)	Use the proxy
API that already sends CORS headers	Direct fetch
Your own API	Add CORS headers on your server

Endpoints

Per-artifact proxy (isolated rate limits, configurable):

GET https://shareout.site/v1/data/{artifactId}/proxy?url=<encoded-url>

Global proxy (shared IP-based rate limit, no config):

GET https://shareout.site/api/proxy?url=<encoded-url>

// Global proxy — simpler, no artifact context needed
const response = await fetch(
  `https://shareout.site/api/proxy?url=${encodeURIComponent('https://api.coingecko.com/api/v3/simple/price?ids=bitcoin&vs_currencies=usd')}`
);

Constraints

Constraint	Value
Method	GET only
Rate limit	100 req/min per artifact
Response size	10 MB max
Timeout	10 seconds
Cache TTL	5 min default

Configuration (owner only)

// Read current config
const config = await fetch(`/v1/data/${artifactId}/proxy/config`, {
  headers: { 'Authorization': `Bearer ${token}` },
}).then(r => r.json());

// Update config
await fetch(`/v1/data/${artifactId}/proxy/config`, {
  method: 'PUT',
  headers: {
    'Authorization': `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    enabled: true,
    allowed_hosts: ['api.weather.gov', 'api.coingecko.com'],
    blocked_hosts: ['internal.company.com'],
    cache_ttl: 600,
    max_requests_per_minute: 50,
  }),
});

Config fields

Field	Type	Default	Description
enabled	boolean	true	Enable or disable the proxy for this artifact
allowed_hosts	string[]	null	Allowlist — null means any host
blocked_hosts	string[]	null	Blocklist
cache_ttl	number	300	Cache TTL in seconds (0–3600)
max_requests_per_minute	number	100	Rate limit (1–1000)

Response headers

Header	Description
X-Proxy-Cache	HIT or MISS
X-RateLimit-Remaining	Requests remaining in the current window

Security

Blocked automatically:

• Internal IPs: 127.0.0.1, localhost, 10.x, 192.168.x, 169.254.x
• Schemes: file://, javascript:, data:
• Set-Cookie headers are stripped from responses

Errors

Code	Meaning
BLOCKED_DESTINATION	Internal IP or disallowed scheme
HOST_NOT_ALLOWED	Host not in allowed_hosts
PROXY_RATE_LIMITED	Rate limit exceeded
FILE_TOO_LARGE	Response exceeds 10 MB
PROXY_ERROR	Upstream request failed