Core API Specifications

Relevant source files

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

• TAMV-MASTER-DOCUMENTATION.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md
• ARCHIVE/tamv-docs-consolidated-2026-02-02/TAMV-OFFICIAL-SYSTEM-DESCRIPTION.md
• ARCHIVE/remaining-docs-consolidated-2026-02-13/REPORTE-AVANCE-TECNICO-COMPLETO.md

The Core API Specifications define the technical interface for the TAMV (Territorio Autónomo de Memoria Viva) ecosystem, a distributed socio-technical infrastructure for digital autonomy. The API facilitates interaction between end-users, creators, and institutions, enabling services ranging from decentralized identity and social interaction to ethical AI applications and blockchain-based asset management.

The system utilizes a Node.js Express-based REST architecture, supplemented by Python FastAPI for AI-specific workloads. It is built to support Web 4.0/5.0 standards, ensuring high scalability and interoperability through a microservices-based approach known as "QuantumPods."
Sources: TAMV-MASTER-DOCUMENTATION.md:14-38, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:275-285, ARCHIVE/remaining-docs-consolidated-2026-02-13/REPORTE-AVANCE-TECNICO-COMPLETO.md:156-160

1. System Architecture and Middleware

The API architecture is structured into seven federated layers, ranging from ontological definitions to the historical-memorial registry. The backend implementation follows a controller-service-repository pattern to ensure separation of concerns and maintainability.

1.1 Middleware Stack

All API requests pass through a robust security and validation pipeline before reaching business logic controllers.

The diagram shows the sequential processing of a request through the security and validation middleware tiers.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md:27-59, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:162-184

1.2 Rate Limiting Tiers

The system enforces specific limits based on the sensitivity and resource intensity of the endpoint.

Tier	Limit	Window	Purpose
Standard API	100 requests	15 minutes	General browsing and fetching
Auth	5 requests	15 minutes	Protection against brute force
Post Creation	10 posts	1 hour	Anti-spam measures
Uploads	20 uploads	1 hour	Resource consumption control

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md:43-47, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:175-180

2. API Endpoint Specifications

2.1 Authentication and Identity

The identity service manages User profiles, DIDs (Decentralized Identifiers), and session persistence via JWT (JSON Web Tokens) with a 15-minute access token and a 7-day refresh token lifecycle.

This sequence details the standard login flow and token generation process.
Sources: TAMV-MASTER-DOCUMENTATION.md:104-106, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:65-71, ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md:65-71

Endpoint	Method	Description	Auth Required
/api/v1/auth/register	POST	Creates a new sovereign identity	No
/api/v1/auth/login	POST	Authenticates and issues JWTs	No
/api/v1/auth/refresh	POST	Renews access token using refresh token	No
/api/v1/auth/logout	POST	Invalidates the current session	Yes

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:65-71, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:255-263

2.2 Social and Content API

The Social Wall API handles posts, interactions, and personalized feeds. It includes automatic count triggers for likes and comments at the database level.

Endpoint	Method	Parameters	Description
/api/v1/posts	GET	page, limit	Paginated list of public posts
/api/v1/posts	POST	content, visibility	Create a new post
/api/v1/posts/:id/like	POST	id (UUID)	Toggle like on a post
/api/v1/feed	GET	page, limit	Personalized content stream

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:82-95, ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md:94-110

3. Ethical AI Integration (Isabella Framework)

The Isabella AI API operates as a non-executive recommendation and explanation engine. It consists of four primary functional applications, primarily accessible through the isabella-ai service pod.

3.1 AI Service Logic Flow

Isabella AI implements a mandatory ethical validation layer before processing any generative request.

The flow represents the "Non-Executive" principle where AI actions are audited for ethical compliance.
Sources: TAMV-MASTER-DOCUMENTATION.md:225-240, ARCHIVE/tamv-docs-consolidated-2026-02-02/TAMV-OFFICIAL-SYSTEM-DESCRIPTION.md:24-35

3.2 AI Core Endpoints

Sources: TAMV-MASTER-DOCUMENTATION.md:118-121, ARCHIVE/remaining-docs-consolidated-2026-02-13/REPORTE-AVANCE-TECNICO-COMPLETO.md:32-38

• POST /v1/chat/completions: Conversational interface with Isabella.
• POST /v1/embeddings: Generates vector embeddings for study or spatial recognition.
• POST /v1/kernel/intent: Evaluates the purpose of user actions (Audit intent).
• GET /health: Returns the status of AI inference runtimes (ONNX/PyTorch).

4. Blockchain and Economic API

The economic API manages the "Quantum-Split" distribution (50% operations, 30% infrastructure, 20% community) and P2P marketplace interactions using the MSR (Memory, Sovereignty, Responsibility) chain.

The ER diagram illustrates the relationship between users, financial transactions, and the immutable MSR registry.
Sources: TAMV-MASTER-DOCUMENTATION.md:195-200, ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:17-25

4.1 Asset Management Endpoints

Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-COMPLETE-IMPLEMENTATION-PLAN.md:280-288

• POST /api/v1/nfts/mint: Mints a new digital asset with metadata.
• POST /api/v1/blockchain/transfer: Executes a value transfer between sovereign wallets.
• GET /api/v1/audit/evidence/:hash: Retrieves cryptographic evidence of an action from the BookPI registry.

5. Security and Data Integrity

The system employs Adaptive Adversarial Containment (AACE) to defend the API. This includes post-quantum cryptography (ML-KEM/ML-DSA) and double-submit cookie patterns for CSRF protection.

5.1 Technical Security Metrics

Metric	Specification	Verification Method
Detection Time	< 2 seconds	Automated penetration tests
False Positive Rate	< 1%	1000+ test scenario audit
Encryption	AES-256 / JWT	Strict TS-Mode validation

Sources: TAMV-MASTER-DOCUMENTATION.md:315-325, ARCHIVE/tamv-docs-consolidated-2026-02-02/TAMV-OFFICIAL-SYSTEM-DESCRIPTION.md:58-65

6. Implementation Summary

The Core API is approximately 68% complete, with the backend core established as production-ready. The system provides 18 verified endpoints across authentication, user management, and social interactions, with specialized AI and blockchain pods currently in the integration phase.
Sources: ARCHIVE/remaining-docs-consolidated-2026-02-13/TAMV-BACKEND-COMPLETE.md:10-15, ARCHIVE/remaining-docs-consolidated-2026-02-13/IMPLEMENTATION-PROGRESS-REPORT.md:150-160