# V2 Core API

Use `core-api-v2` for backend capabilities that should not live in the client.

Base URL:

```text
https://krow-core-api-v2-e3g6witsvq-uc.a.run.app
```

## 1) Route summary

| Method | Route | Purpose |
| --- | --- | --- |
| `POST` | `/core/upload-file` | Upload file to Google Cloud Storage |
| `POST` | `/core/create-signed-url` | Generate a read URL for an uploaded file |
| `POST` | `/core/invoke-llm` | Run a model call |
| `POST` | `/core/rapid-orders/transcribe` | Turn uploaded audio into text |
| `POST` | `/core/rapid-orders/parse` | Turn order text into structured order data |
| `POST` | `/core/verifications` | Create a verification job |
| `GET` | `/core/verifications/:verificationId` | Fetch verification status |
| `POST` | `/core/verifications/:verificationId/review` | Apply manual review decision |
| `POST` | `/core/verifications/:verificationId/retry` | Retry a verification job |
| `GET` | `/health` | Health check |

## 2) Upload file

Route:

```text
POST /core/upload-file
```

Send multipart form data:
- `file`: required
- `category`: optional string
- `visibility`: `public` or `private`

Example response:

```json
{
  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
  "contentType": "application/pdf",
  "size": 12345,
  "bucket": "krow-workforce-dev-private",
  "path": "uploads/<uid>/file.pdf",
  "requestId": "uuid"
}
```

## 3) Create signed URL

Route:

```text
POST /core/create-signed-url
```

Example request:

```json
{
  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/file.pdf",
  "expiresInSeconds": 300
}
```

Example response:

```json
{
  "signedUrl": "https://...",
  "expiresAt": "2026-03-11T18:30:00.000Z",
  "requestId": "uuid"
}
```

## 4) Invoke model

Route:

```text
POST /core/invoke-llm
```

Example request:

```json
{
  "prompt": "Summarize this staffing request",
  "fileUrls": ["gs://krow-workforce-dev-private/uploads/<uid>/notes.pdf"],
  "responseJsonSchema": {
    "type": "object",
    "properties": {
      "summary": { "type": "string" }
    },
    "required": ["summary"]
  }
}
```

Example response:

```json
{
  "result": {
    "summary": "..."
  },
  "model": "vertex model name",
  "latencyMs": 1200,
  "requestId": "uuid"
}
```

## 5) Rapid order helpers

### Transcribe

```text
POST /core/rapid-orders/transcribe
```

Example request:

```json
{
  "audioFileUri": "gs://krow-workforce-dev-private/uploads/<uid>/note.m4a",
  "locale": "en-US",
  "promptHints": ["staffing order", "shift details"]
}
```

### Parse

```text
POST /core/rapid-orders/parse
```

Example request:

```json
{
  "text": "Need two baristas tomorrow from 8am to 4pm at Google Mountain View Cafe",
  "locale": "en-US",
  "timezone": "America/Los_Angeles"
}
```

## 6) Verification routes

### Create verification

```text
POST /core/verifications
```

Example request:

```json
{
  "type": "attire",
  "subjectType": "staff",
  "subjectId": "staff-uuid",
  "fileUri": "gs://krow-workforce-dev-private/uploads/<uid>/attire.jpg",
  "rules": {
    "label": "black shoes"
  }
}
```

### Get verification

```text
GET /core/verifications/:verificationId
```

### Manual review

```text
POST /core/verifications/:verificationId/review
```

Example request:

```json
{
  "decision": "APPROVED",
  "note": "Manual review passed"
}
```

### Retry

```text
POST /core/verifications/:verificationId/retry
```

## 7) Caveat

Verification state is not yet stored in `krow-sql-v2`.

Use these routes now for frontend integration, but do not depend on verification history being durable until the persistence work lands.
