Skip to Content
OrbixDocs
Block SDK · Guides

Call external APIs

Fetch JSON endpoints with useOrbixFetch, send mutations with useOrbixRequest, and declare allowed outbound domains.

Blocks can make outbound HTTP requests with useOrbixFetch, useOrbixRequest, and orbixFetch. Because community blocks run inside a workspace that may also contain private notes, outbound requests are gated by both your manifest declaration and orbixEgressFirewall.

Declaring network capabilities

Community blocks have network.domains: [] by default — all outbound requests are denied until you list the hostnames your block calls in manifest.capabilities.network:

manifest.json
{
  "id": "acme.weather-card",
  "name": "Weather Card",
  "version": "1.0.0",
  "sdk": "^3.0.0",
  "capabilities": {
    "network": {
      "domains": ["api.open-meteo.com"],
      "methods": ["GET"]
    }
  }
}

Reactive GET requests (useOrbixFetch)

useOrbixFetch<T>(url, options?) runs a request on mount (unless lazy: true), tracks loading and error strings, and supports caching and polling:

src/WeatherBlock.tsx
import {
  defineBlock,
  useOrbixFetch,
  type BlockRenderProps,
} from '@orbixdocs/sdk';

interface ForecastResponse {
  current_weather?: {
    temperature: number;
    windspeed: number;
  };
}

export default defineBlock({
  manifest: {
    id: 'acme.weather-card',
    name: 'Weather Card',
    version: '1.0.0',
    sdk: '^3.0.0',
    capabilities: {
      network: {
        domains: ['api.open-meteo.com'],
        methods: ['GET'],
      },
    },
  },
  component(_props: BlockRenderProps) {
    const { data, loading, error, refetch } = useOrbixFetch<ForecastResponse>(
      'https://api.open-meteo.com/v1/forecast?latitude=37.77&longitude=-122.42&current_weather=true',
      {
        cacheTtl: 60_000,
        pollInterval: 0,
      }
    );

    return (
      <div
        style={{
          padding: 16,
          borderRadius: 12,
          background: 'var(--orbix-card-bg, #16171b)',
          border: '1px solid var(--orbix-surface-border, #2a2b32)',
          color: 'var(--orbix-text-primary, #f4f4f5)',
        }}
      >
        {loading && <div>Loading forecast...</div>}
        {error && <div>Request failed: {error}</div>}
        {data?.current_weather && (
          <div>
            San Francisco: {data.current_weather.temperature}°C (wind{' '}
            {data.current_weather.windspeed} km/h)
          </div>
        )}
        <button type="button" onClick={refetch} style={{ marginTop: 8 }}>
          Refresh
        </button>
      </div>
    );
  },
});

Imperative mutations (useOrbixRequest and orbixFetch)

For POST, PUT, PATCH, or DELETE requests triggered by a button click, use useOrbixRequest or orbixFetch.

When calling orbixFetch directly inside an event handler, always read useBlockId() at the component top level and pass { blockId } in the request options. Without blockId, the call is attributed to 'anonymous-block' and fails closed.

src/WebhookTrigger.tsx
import { useBlockId, useOrbixRequest, orbixFetch } from '@orbixdocs/sdk';

export function WebhookButtons() {
  const blockId = useBlockId();

  // Option A: Hook with built-in loading / error state
  const { loading, error, execute } = useOrbixRequest<{ ok: boolean }>(
    'https://api.example.com/webhooks/ping',
    { method: 'POST' }
  );

  // Option B: Low-level Response access
  const checkHealth = async () => {
    const res = await orbixFetch('https://api.example.com/health', {
      method: 'GET',
      blockId,
    });
    return res.status;
  };

  return (
    <div>
      <button
        type="button"
        disabled={loading}
        onClick={() => void execute({ event: 'manual_ping' })}
      >
        Send ping
      </button>
      <button type="button" onClick={() => void checkHealth()}>
        Check status
      </button>
      {error && <span>{error}</span>}
    </div>
  );
}

Egress firewall rules and limits

How outbound traffic is checked depends on which runtime executes your block:

  1. React SDK blocks (orbixEgressFirewall):
    • Allows only http:, https:, ws:, and wss: schemes.
    • Blocks private/loopback IP ranges and cloud metadata addresses (SSRF protection; localhost is permitted only when Orbix itself is served from localhost).
    • Blocks Orbix authentication paths (/api/auth* and /auth/v1*).
    • Blocks requests carrying registered secret fingerprints or known secret prefixes in unauthorized payloads (DLP check).
    • Taint rule: If a community block has read document, workspace, database, or cross-block data, orbixEgressFirewall marks that instance as tainted and blocks all subsequent outbound requests from it.
    • Requires an installed permission grant from BlockPermissionSheet (or authorPreview: true while editing in Block Studio).
  2. HTML and polyglot blocks (OrbixHtmlFrame):
    • The runner iframe's HTTP Content Security Policy (connect-src blob: data:) blocks direct browser fetch, XMLHttpRequest, WebSocket, and EventSource connections inside the frame.
    • fetch, XMLHttpRequest, and navigator.sendBeacon are shimmed over postMessage to the host's hostFetch handler, which verifies manifest.capabilities.network.domains via capabilityEngine.verifyNetwork and enforces:
      • 10 MB max request and response size
      • 30 s request timeout
      • 8 concurrent in-flight requests per block (exceeding throws SecurityCapabilityError with capability: 'network:rate')
      • credentials: 'omit' (host cookies are never sent)

WebSockets (useOrbixWebSocket)

useOrbixWebSocket (exported from both @orbixdocs/sdk and @orbixdocs/sdk/realtime) manages WebSocket connections with reconnect backoff in React SDK blocks when capabilities.network.websocket is true and the target host is permitted by orbixEgressFirewall. WebSockets are not available inside cross-origin HTML/polyglot frames because of connect-src blob: data:.

On this page