Skip to main content

​
API Overview

AFFiNE provides a comprehensive GraphQL API for managing workspaces, documents, users, and collaborative features. The API is designed for building integrations, automation tools, and custom clients.

​
Base URL

The GraphQL API endpoint is available at: 
https://your-affine-instance.com/graphql
For self-hosted instances, replace your-affine-instance.com with your server’s domain.

​
GraphQL Endpoint

AFFiNE uses GraphQL as its primary API protocol, providing a single endpoint for all operations:
  • Endpoint: /graphql
  • Methods: POST (for queries and mutations), GET (for GraphiQL in development)
  • Content-Type: application/json

​
Why GraphQL?

  • Flexible Queries: Request exactly the data you need
  • Type Safety: Strongly typed schema with introspection
  • Single Endpoint: All operations through one URL
  • Efficient: Reduce over-fetching and under-fetching

​
GraphiQL Playground

In development mode, you can access the interactive GraphiQL playground: 
http://localhost:3010/graphql
The playground provides:
  • Interactive query builder
  • Schema documentation
  • Auto-completion
  • Query history

​
Rate Limiting

AFFiNE implements rate limiting to ensure service stability:
Default Rate Limits:
  • Default Throttler: 120 requests per 60 seconds
  • Strict Throttler: 20 requests per 60 seconds (for sensitive operations)
  • Authenticated Users: Higher limits and bypass on certain endpoints
Rate limits are applied per user/session. Headers in the response indicate your current limit status: 
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 115
X-RateLimit-Reset: 1678901234

​
Handling Rate Limits

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response: 
{
  "errors": [
    {
      "message": "Too Many Requests",
      "extensions": {
        "code": "TOO_MANY_REQUEST"
      }
    }
  ]
}
Implement exponential backoff when you receive rate limit errors. Wait for the X-RateLimit-Reset time before retrying.

​
Making Your First Request

Here’s a simple example to get the current user: 
curl -X POST https://your-affine-instance.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -d '{
    "query": "query { currentUser { id email name } }"
  }'

​
Response Format

All GraphQL responses follow this structure: 
{
  "data": {
    // Your requested data here
  },
  "errors": [
    // Any errors that occurred
  ]
}

​
Successful Response

{
  "data": {
    "currentUser": {
      "id": "user123",
      "email": "user@example.com",
      "name": "John Doe"
    }
  }
}

​
Error Response

{
  "errors": [
    {
      "message": "Authentication required",
      "extensions": {
        "code": "AUTHENTICATION_REQUIRED",
        "status": 401
      }
    }
  ],
  "data": null
}

​
Error Codes

AFFiNE uses standardized error codes to help you handle different scenarios:
CodeDescription
AUTHENTICATION_REQUIREDUser must be authenticated
ACCESS_DENIEDUser doesn’t have permission
NOT_FOUNDResource doesn’t exist
VALIDATION_ERRORInput validation failed
SPACE_NOT_FOUNDWorkspace not found
DOC_NOT_FOUNDDocument not found
TOO_MANY_REQUESTRate limit exceeded
QUOTA_EXCEEDEDStorage or feature quota exceeded
COPILOT_QUOTA_EXCEEDEDAI copilot quota exceeded
BLOB_QUOTA_EXCEEDEDFile storage quota exceeded
For a complete list of error codes, see the ErrorNames enum in the GraphQL schema.

​
API Versioning

The AFFiNE API uses client version headers to ensure compatibility: 
x-affine-client-version: 0.25.0
  • Minimum Required Version: >=0.25.0
  • Recommended: Always use the latest stable client version
Clients with versions below the minimum requirement will receive an UNSUPPORTED_CLIENT_VERSION error and be signed out automatically.

​
Schema Introspection

GraphQL supports introspection, allowing you to query the schema itself: 
query {
  __schema {
    types {
      name
      description
    }
  }
}
You can also query specific types: 
query {
  __type(name: "UserType") {
    name
    fields {
      name
      type {
        name
      }
    }
  }
}

​
Core Resources

The API provides access to these primary resources:
  • Users: User accounts, profiles, and authentication
  • Workspaces: Collaborative workspace management
  • Documents: Pages and docs within workspaces
  • Blobs: File attachments and media
  • Comments: Document comments and replies
  • Copilot: AI-powered features and chat sessions
  • Notifications: User notifications and alerts
  • Subscriptions: Payment and subscription management

​
Next Steps

  1. Set up authentication - Learn how to authenticate API requests See Authentication
  2. Explore the schema - Browse available queries and mutations in GraphiQL
  3. Try example queries - Start with simple operations like fetching workspaces
  4. Build your integration - Combine operations to create powerful workflows

​
Additional Resources

  • GraphQL Schema: Available at /schema.gql in the repository
  • GraphiQL Playground: Available in development mode
  • Community: Join our Discord for API discussions
  • GitHub: Report issues or contribute to the API