# M4 Core API Frontend Guide (Dev)

Status: Active  
Last updated: 2026-02-24  
Audience: Web and mobile frontend developers

## 1) Base URLs (dev)
1. Core API: `https://krow-core-api-e3g6witsvq-uc.a.run.app`

## 2) Auth requirements
1. Send Firebase ID token on protected routes:
```http
Authorization: Bearer <firebase-id-token>
```
2. Health route is public:
- `GET /health`
3. All other routes require Firebase token.

## 3) Standard error envelope
```json
{
  "code": "STRING_CODE",
  "message": "Human readable message",
  "details": {},
  "requestId": "uuid"
}
```

## 4) Core API endpoints

## 4.1 Upload file
1. Route: `POST /core/upload-file`
2. Alias: `POST /uploadFile`
3. Content type: `multipart/form-data`
4. Form fields:
- `file` (required)
- `visibility` (optional: `public` or `private`, default `private`)
- `category` (optional)
5. Accepted file types:
- `application/pdf`
- `image/jpeg`
- `image/jpg`
- `image/png`
6. Max upload size: `10 MB` (default)
7. Current behavior: real upload to Cloud Storage (not mock)
8. Success `200` example:
```json
{
  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/173...",
  "contentType": "application/pdf",
  "size": 12345,
  "bucket": "krow-workforce-dev-private",
  "path": "uploads/<uid>/173..._file.pdf",
  "requestId": "uuid"
}
```

## 4.2 Create signed URL
1. Route: `POST /core/create-signed-url`
2. Alias: `POST /createSignedUrl`
3. Request body:
```json
{
  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
  "expiresInSeconds": 300
}
```
4. Security checks:
- bucket must be allowed (`krow-workforce-dev-public` or `krow-workforce-dev-private`)
- path must be owned by caller (`uploads/<caller_uid>/...`)
- object must exist
- `expiresInSeconds` must be `<= 900`
5. Success `200` example:
```json
{
  "signedUrl": "https://storage.googleapis.com/...",
  "expiresAt": "2026-02-24T15:22:28.105Z",
  "requestId": "uuid"
}
```
6. Typical errors:
- `400 VALIDATION_ERROR` (bad payload or expiry too high)
- `403 FORBIDDEN` (path not owned by caller)
- `404 NOT_FOUND` (object does not exist)

## 4.3 Invoke model
1. Route: `POST /core/invoke-llm`
2. Alias: `POST /invokeLLM`
3. Request body:
```json
{
  "prompt": "Return JSON with keys summary and risk.",
  "responseJsonSchema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" },
      "risk": { "type": "string" }
    },
    "required": ["summary", "risk"]
  },
  "fileUrls": []
}
```
4. Current behavior: real Vertex model call (not mock)
- model: `gemini-2.0-flash-001`
- timeout: `20 seconds`
5. Rate limit:
- per-user `20 requests/minute` (default)
- on limit: `429 RATE_LIMITED`
- includes `Retry-After` header
6. Success `200` example:
```json
{
  "result": { "summary": "text", "risk": "Low" },
  "model": "gemini-2.0-flash-001",
  "latencyMs": 367,
  "requestId": "uuid"
}
```

## 5) Frontend fetch examples (web)

## 5.1 Signed URL request
```ts
const token = await firebaseAuth.currentUser?.getIdToken();
const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/create-signed-url', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    fileUri: 'gs://krow-workforce-dev-private/uploads/<uid>/file.pdf',
    expiresInSeconds: 300,
  }),
});
const data = await res.json();
```

## 5.2 Model request
```ts
const token = await firebaseAuth.currentUser?.getIdToken();
const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/invoke-llm', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${token}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    prompt: 'Return JSON with status.',
    responseJsonSchema: {
      type: 'object',
      properties: { status: { type: 'string' } },
      required: ['status'],
    },
  }),
});
const data = await res.json();
```

## 6) Notes for frontend team
1. Use canonical `/core/*` routes for new work.
2. Aliases exist only for migration compatibility.
3. `requestId` in responses should be logged client-side for debugging.
4. For 429 on model route, retry with exponential backoff and respect `Retry-After`.
5. Verification workflows (`attire`, `government_id`, `certification`) are defined in:
   `docs/MILESTONES/M4/planning/m4-verification-architecture-contract.md`.