API Controllers & Endpoints

Relevant source files

The following files were used as context for generating this wiki page:

• apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt
• apps/api/src/main/kotlin/com/briefy/api/api/TopicController.kt
• apps/web/src/lib/api/sources.ts
• apps/web/src/lib/api/types.ts
• apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt
• apps/api/src/test/kotlin/com/briefy/api/api/TopicControllerTest.kt

The API Controllers in the Briefy ecosystem serve as the entry point for handling client requests, coordinating with application services, and managing the lifecycle of knowledge graph entities such as Sources and Topics. These controllers are built using Spring Boot's @RestController architecture and follow a RESTful pattern to provide CRUD operations, search capabilities, and specialized processing triggers like AI narration or extraction retries.

The system is organized into distinct domain-driven controllers located in the com.briefy.api.api package. The SourceController manages content ingestion and metadata, while the TopicController handles the categorization and linking of those sources. Interaction with these endpoints is facilitated on the frontend via TypeScript-based API clients that map request/response structures to strongly typed interfaces.

Sources: apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:18-25, apps/web/src/lib/api/types.ts:1-10, AGENTS.md:10-15

Source Management Controller

The SourceController is the primary interface for managing content items (Sources). It supports a wide range of operations from initial URL submission to manual content updates and AI-driven narration requests.

Endpoint Overview: Source Operations

The following table details the primary endpoints available for source management:

Method	Path	Description	Key Parameters
POST	/api/sources	Creates a new source from a URL and triggers extraction.	url (String)
GET	/api/sources	Lists sources with support for pagination, filtering, and sorting.	status, cursor, topicIds, sort
GET	/api/sources/{id}	Retrieves detailed information for a specific source.	id (UUID)
GET	/api/sources/search	Performs a full-text search across active sources.	q (Query string), limit
DELETE	/api/sources/{id}	Deletes a source; hides it from active lists.	id (UUID)
POST	/api/sources/archive-batch	Atomically archives multiple sources.	sourceIds (List)

Sources: apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:29-160, apps/web/src/lib/api/sources.ts:14-110

Content Processing & Lifecycle

Sources move through various states (e.g., submitted, extracting, active, failed). The controller provides endpoints to manually intervene when automated processes fail or require updates.

Advanced Source Features

• Narration: Triggers AI voice generation via POST /{id}/narrate. Clients can also request cost/length estimates via GET /{id}/narrate/estimate.
• Manual Content: If automated extraction fails, users can provide text directly via POST /{id}/content.
• Topic Linking: Provides endpoints to view active topics for a source or suggested topics generated by AI.

Sources: apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:76-114, apps/web/src/lib/api/types.ts:40-60

Topic Management Controller

The TopicController manages the taxonomy of the knowledge graph. It allows for the creation of topics, linking sources to those topics, and managing AI-suggested categories.

Topic Operations

Method	Path	Description
POST	/api/topics	Creates a new topic and optionally links initial source IDs.
GET	/api/topics	Lists active or suggested topics based on status filters.
GET	/api/topics/{id}	Returns a detailed view of a topic including all its linked sources.
POST	/api/sources/{id}/topics/apply	Confirms AI-suggested topics for a specific source.

Sources: apps/api/src/main/kotlin/com/briefy/api/api/TopicController.kt:21-50, apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:180-210

Topic Suggestion Workflow

AI automatically suggests topics for new sources. Users must "apply" these suggestions to move them from a suggested state to an active state.

Data Transfer Objects (DTOs)

The API uses structured request and response objects to ensure type safety between the Kotlin backend and the TypeScript frontend.

Primary Response Structures

// Example Source Response structure found in SourceController
data class SourceResponse(
    val id: UUID,
    val url: SourceUrlResponse,
    val status: SourceStatus,
    val sourceType: SourceType,
    val content: SourceContentResponse?,
    val metadata: SourceMetadataResponse?,
    val topics: List<SourceTopicChipResponse>
)

Sources: apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:215-240, apps/web/src/lib/api/types.ts:47-68

List Pagination & Filtering

The listSources endpoint utilizes cursor-based pagination to handle large libraries efficiently. It supports the following query parameters:

• limit: Number of items to return (default is often 20).
• cursor: Base64 encoded string containing timestamp and ID to fetch the next page.
• status: Filters by active, archived, or failed.
• sort: Supports values like newest or longest (reading time).

Sources: apps/api/src/main/kotlin/com/briefy/api/api/SourceController.kt:42-55, apps/api/src/test/kotlin/com/briefy/api/api/SourceControllerTest.kt:135-180

Conclusion

The API layer of Briefy provides a robust and strictly typed interface for managing the knowledge graph. By separating concerns between Source processing (ingestion, extraction, narration) and Topic organization (categorization, linking), the system supports complex AI-driven workflows while remaining performant through features like batch operations and cursor-based pagination.