Entities
This page documents the core data types in Whitepapper using TypeScript syntax for clarity.
Project
A project is the top-level content container. It owns collections and papers, and has its own API key.
typescript
interface Project {
projectId: string;
ownerId: string;
name: string;
slug: string;
description: string;
contentGuidelines: string;
logoUrl?: string | null;
isPublic: boolean;
pagesNumber: number;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}Fields
| Field | Type | Description |
|---|---|---|
| projectId | string | Unique project identifier |
| ownerId | string | User ID of the owner |
| name | string | Display name |
| slug | string | URL-safe identifier, unique per user |
| description | string | Project description (Markdown) |
| contentGuidelines | string | Instructions for AI-assisted writing |
| logoUrl | string | null | Project logo URL |
| isPublic | boolean | Whether the project is publicly accessible |
| pagesNumber | number | Count of papers in this project |
Collection
A collection groups related papers inside a project.
typescript
interface Collection {
collectionId: string;
projectId: string;
ownerId: string;
name: string;
slug: string;
description: string;
isPublic: boolean;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
pagesNumber: number;
}Fields
| Field | Type | Description |
|---|---|---|
| collectionId | string | Unique collection identifier |
| projectId | string | Parent project ID |
| ownerId | string | User ID of the owner |
| name | string | Display name |
| slug | string | URL-safe identifier, unique per project |
| description | string | Collection description |
| isPublic | boolean | Whether the collection is publicly accessible |
| pagesNumber | number | Count of papers in this collection |
Paper
A paper is a single Markdown document — the core unit of content.
typescript
interface Paper {
paperId: string;
collectionId?: string | null;
projectId?: string | null;
ownerId: string;
thumbnailUrl?: string | null;
title: string;
slug: string;
body: string; // Markdown content
status: "draft" | "published" | "archived";
metadata?: PaperMetadata | null;
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}Status Values
| Status | Meaning |
|---|---|
draft | Visible in the editor only |
published | Publicly accessible if parent is public |
archived | Removed from public view |
PaperMetadata
Full metadata attached to each paper, used for SEO and social sharing.
typescript
interface PaperMetadata {
title: string;
metaDescription: string;
canonical: string;
robots: string;
ogTitle: string;
ogDescription: string;
ogImage: string;
ogImageWidth: number; // default: 1200
ogImageHeight: number; // default: 630
ogImageAlt: string;
ogLocale: string; // default: "en_US"
ogPublishedTime: string; // ISO 8601
ogModifiedTime: string; // ISO 8601
ogAuthorUrl: string;
ogTags: string[];
twitterTitle: string;
twitterDescription: string;
twitterImage: string;
twitterImageAlt: string;
twitterCreator?: string | null;
headline: string;
abstract: string;
keywords: string;
articleSection: string;
wordCount: number;
readingTimeMinutes: number;
inLanguage: string;
datePublished: string; // ISO 8601
dateModified: string; // ISO 8601
authorName: string;
authorHandle: string;
authorUrl: string;
authorId: string;
coverImageUrl: string;
publisherName: string;
publisherUrl: string;
isAccessibleForFree: boolean;
license: string;
keyTakeaways?: string[] | null;
faq?: Array<{
question: string;
answer: string;
}> | null;
authorBio?: string | null;
jsonLd?: Record<string, any> | Array<Record<string, any>> | null;
}User
The root entity that owns all content.
typescript
interface User {
userId: string;
displayName?: string | null;
description: string;
email?: string | null;
avatarUrl?: string | null;
username: string; // Public handle
plan: "free" | "pro";
preferences?: {
showKeyboardEffect?: boolean;
typingSoundEnabled?: boolean;
hashnodeIntegrated?: boolean;
devtoIntegrated?: boolean;
};
createdAt: string; // ISO 8601
updatedAt: string; // ISO 8601
}Related
- Introduction — Content hierarchy explained.
- Dev API Quickstart — Fetch entities via the API.
- Auto Tags — How metadata maps to SEO output.
