🔌 API Reference

The deployed Cloud Functions, callable contracts, REST routes, and MCP boundary.

:::info Verification scope This page verifies the TypeScript/Firebase surface in acesense-auth-function and the rewrites in acesense-api-hosting. GPU-provider wire details are deliberately omitted from this non-GPU audit. :::

Runtime

• Firebase project: acesense-prod
• Region: europe-west1
• Runtime: Node.js 22
• Function entry point: acesense-auth-function/index.ts

Mobile upload callables

requestUploadPath

Authenticated callable with App Check policy from shared/app-check.ts. It requires durable AI consent, an active trial/paid entitlement, available monthly budget, and available daily/concurrent quota.

interface VideoMetadata {
  fileName: string;
  fileSize: number;
  duration: number;
  width: number;
  height: number;
  format: string;
  codec?: string;
}

interface UploadPathResponse {
  uploadPath: string;
  resultPath: string;
  jobId: string;
  sessionId: string;
  expiresAt: number;
  quota: {
    plan: string;
    uploadsToday: number;
    uploadsPerDay: number;
    concurrent: number;
    concurrentLimit: number;
    resetsAt: number;
  };
}

The server ignores client session identifiers and generates its own. Paths are:

videos/{uid}/{sessionId}/{sessionId}_chunk_001.mp4
results/{uid}/{sessionId}/{sessionId}_combined.json

Limits from shared/config.ts: 2 GiB, 2 hours, and mp4, mov, avi, or mkv metadata. Current Storage rules permit owner uploads only when the object is video/mp4, so mobile uploads use the generated .mp4 path.

reportUploadFailure

Request: { jobId: string, errorMessage?: string }.

Only the owner may report failure, and only while the job remains pending. It fails the job and releases the reserved concurrency slot. A late report cannot cancel processing that already started.

checkJobStatus

Authenticated status reconciliation for a job owned by the caller. The client uses it as a backend-authoritative status refresh; Firestore remains the live UI source.

mergeChunkResults

Authenticated compatibility callable accepting { sessionId: string, totalChunks: number }. The shipped client uploads one file, but the server retains this contract for legacy/deferred chunking.

User and account callables

Function	Purpose
createUserDocument	Auth-create trigger; seeds trial/profile state
deleteUserDocument	Auth-delete trigger; cascades user data
markEmailVerified	Records verified-email state and welcome workflow
sendPasswordResetCustom	Sends the custom reset flow
exportUserData	Creates a user data export
requestAccountDeletion	Starts account deletion
deleteSession	Deletes a job and its Storage artifacts

Coach callables

becomeCoach, createCoachLink, respondToCoachLink, listCoachLinks, addCoachNote, and listCoachNotes implement two-sided coach/player consent. All are authenticated v2 callables in europe-west1.

Admin callables

Admin functions use the shared requireAdmin guard. They include retry/status, user, plan, suspension, API-key balance/revocation, moderation, impersonation, Storage browsing, and purge operations. bootstrapAdminClaims self-heals the custom claim for a verified allowlisted admin.

Public REST API

Firebase Hosting preserves the /v1/** path and rewrites it to apiServer.

Method	Route	Auth
GET	/v1/healthz	None
GET	/v1/pricing	None
POST	/v1/jobs	API key
GET	/v1/jobs/:jobId	Owning API key
GET	/v1/jobs/:jobId/result	Owning API key
GET	/v1/usage	API key

API keys are created and revoked through Firebase callables: createApiKey, listApiKeys, and revokeApiKey. See Agent API + MCP for billing and key details.

MCP

https://api.acesense.io/mcp rewrites to mcpServer. GET returns endpoint metadata; POST uses streamable HTTP with MCP protocol 2025-06-18.

Scheduled and event functions

Function	Trigger
processVideoOnUpload	Storage finalize under videos/
onResultUploaded	Storage finalize under results/
reconcileStuckJobs	Every 60 minutes
purgeExpiredSessions	Every 24 hours
generateSessionInsights	Combined-result Storage finalize
syncTierToPlan	users/{uid} write
onFeedbackCreated, onDocsFeedbackCreated	Firestore create

Related

• Configuration
• Job document
• Security