Skip to main content

API Overview

The DFOS API provides programmatic access to identities, spaces, posts, and media. It's a REST-style HTTP API with full OpenAPI specification and type-safe client support.

Interactive API Reference​

Complete API documentation with try-it functionality:

→ Interactive API Reference​

The reference includes all endpoints, schemas, authentication requirements, and live testing.

How it works: The interactive reference is generated from the OpenAPI specification (static/openapi.json) using Scalar's API documentation tool. The spec is contract-first—defined in TypeScript using oRPC and Zod schemas, then compiled to OpenAPI format during the docs build process.

Quick Start​

1. Authenticate

DFOS uses session-based authentication powered by Clerk. Obtain a session through the authentication flow.

2. Get your identity

GET /identity/current

Use the special value 'current' to reference your own identity or account without knowing the ID.

3. Create your first space

POST /spaces
{
  "displayName": "My Space",
  "description": "A private space for collaboration"
}

4. Generate your admin invite

POST /spaces/{spaceId}/my-invite
{
  "maxUses": 10,
  "expiresInMinutes": 10080,
  "joinModeOverride": "instant"
}

Each admin gets one invite link. Share the generated code to add members.

5. Build from there

See the namespace guides below for detailed workflows.

API Guides​

Detailed guides for each major namespace:

  • Identity API - Managing identities, profiles, and usernames
  • Spaces API - Creating spaces, managing membership, join modes, and access control
  • Posts API - Creating posts, comments, reactions, and bookmarks
  • Media API - Uploading and managing images and media

Technology Stack​

  • oRPC: Type-safe RPC framework with automatic OpenAPI generation
  • Zod schemas: Full runtime and compile-time type safety
  • Contract-first: API spec is the source of truth

Authentication​

Account model: Email-verified accounts via Clerk. Each account can have multiple identities.

Sessions: After authentication, include session token in requests via Authorization: Bearer <token> header.

Special value: Use 'current' to reference your own resources:

  • GET /identity/current - Your current identity
  • GET /accounts/current - Your account information

Key Namespaces​

System - Version info and health checks

Identity - Get, update, and manage identities and profiles

Accounts - Account information and changelog tracking

Session - Session details and activity

Device Auth - OAuth device flow for CLI and headless authentication

Spaces - Full CRUD for spaces, membership, invites, applications, and domains

Applications - Submit, manage, and review space join applications

Posts - Create posts, add comments, react, bookmark

Media - Upload images and media files

Notifications - Activity notifications, read state, and badge counts

Chat - Stream Chat integration for real-time communication

Authorization​

Operations require specific permissions:

Identity operations: Authentication required. Operations on other identities require shared space membership.

Space operations: Public spaces can be viewed by anyone (limited info). Private spaces and full details require membership. Admin role required for management (invites, member removal, settings).

Content operations: Space membership required for viewing. Member role required for creation.

Error Handling​

Standard HTTP status codes:

  • 200: Success
  • 400: Bad request (validation failed)
  • 401: Unauthorized (not authenticated)
  • 403: Forbidden (authenticated but insufficient permissions)
  • 404: Not found (or not visible due to privacy)
  • 409: Conflict (resource already exists)
  • 500: Internal server error

Error responses include structured messages with codes for programmatic handling.

TypeScript SDK​

Status: No official SDK currently available.

Recommended approach: Use standard HTTP clients (fetch, axios) with TypeScript types generated from the OpenAPI specification. The contract-first API design ensures type safety at the schema level.

Next Steps​

  • Explore the Interactive API Reference for complete endpoint documentation
  • Read the namespace guides above for detailed workflows
  • Review Concepts for product-level understanding
  • Check Protocol for technical specifications