Skip to main content

​
Introduction

OneGlance provides a type-safe tRPC API for tracking how AI providers mention your brand. The API uses tRPC for end-to-end type safety and superjson for data serialization, supporting advanced JavaScript types like Date, Map, and Set.

​
Authentication

The OneGlance API uses session-based authentication powered by Better Auth. All API requests must include valid session credentials.

​
Authentication Types

The API has three authentication levels:
  • Public Procedures: No authentication required
  • Protected Procedures: Requires authenticated user session
  • Authorized Workspace Procedures: Requires authentication and workspace membership

​
Making Authenticated Requests

Authentication is handled automatically through session cookies when using the tRPC client. All workspace-specific endpoints require a workspaceId parameter to identify which workspace the operation applies to. 
const result = await trpc.workspace.getById.query({
  workspaceId: "ws_123456789"
});

​
Request Format

OneGlance uses tRPC which provides type-safe RPC-style calls. There are two types of procedures:

​
Queries

Queries are used for data retrieval (GET operations): 
const workspaces = await trpc.workspace.listAllForUser.query();

​
Mutations

Mutations are used for data modification (POST/PUT/DELETE operations): 
const workspace = await trpc.workspace.create.mutate({
  name: "My Workspace",
  slug: "my-workspace",
  domain: "example.com",
  organizationName: "My Organization"
});

​
Error Handling

The API uses a structured error format with domain-specific error codes: 
{
  error: {
    message: "Only workspace owners can update workspace details.",
    code: "VALIDATION_ERROR",
    data: {
      zodError: null,
      domainCode: "VALIDATION_ERROR",
      meta: {},
      isOperational: true
    }
  }
}

​
Error Types

  • ValidationError: Input validation failed or business rule violated
  • AuthError: Authentication or authorization failed
  • TRPCError: General tRPC errors (BAD_REQUEST, UNAUTHORIZED, etc.)

​
Zod Validation Errors

When input validation fails, the error includes a zodError field with detailed validation information: 
{
  error: {
    data: {
      zodError: {
        fieldErrors: {
          email: ["Invalid email"]
        }
      }
    }
  }
}

​
Rate Limits

The API implements rate limiting on specific endpoints to ensure fair usage:
EndpointLimitWindow
workspace.create3 requests1 hour
workspace.joinByCode5 requests15 minutes
prompt.store20 requests1 minute
analysis.analyzeMetrics10 requests1 minute
agent.run3 requests1 minute
When rate limits are exceeded, the API returns a TOO_MANY_REQUESTS error.

​
Data Serialization

The API uses superjson for data serialization, which means:
  • Date objects are automatically serialized and deserialized
  • Special types like Map, Set, BigInt are supported
  • Undefined values are preserved (unlike standard JSON)

​
API Routers

The OneGlance API is organized into the following routers:
  • Workspace - Manage workspaces, organizations, and team members
  • Prompts - Store and retrieve prompts for analysis
  • Analysis - Analyze prompts to extract brand mentions and metrics
  • Agent - Run automated agents to collect and analyze prompts

​
Next Steps

Workspace API

Create and manage workspaces

Prompts API

Store and retrieve prompts

Analysis API

Analyze brand mentions

Agent API

Run automated agents