docs(m4): scope api docs to core endpoints only

This commit is contained in:
zouantchaw
2026-02-24 10:28:44 -05:00
parent d5e49ca148
commit 07dd6609d9
3 changed files with 81 additions and 191 deletions

View File

@@ -6,7 +6,6 @@ Audience: Web and mobile frontend developers
## 1) Base URLs (dev)
1. Core API: `https://krow-core-api-e3g6witsvq-uc.a.run.app`
2. Command API: `https://krow-command-api-e3g6witsvq-uc.a.run.app`
## 2) Auth requirements
1. Send Firebase ID token on protected routes:
@@ -119,31 +118,9 @@ Authorization: Bearer <firebase-id-token>
}
```
## 5) Command API endpoint currently ready for consumption
## 5) Frontend fetch examples (web)
## 5.1 Create order command (scaffold)
1. Route: `POST /commands/orders/create`
2. Required headers:
- `Authorization: Bearer <firebase-id-token>`
- `Idempotency-Key: <unique-client-key>`
3. Current behavior:
- validates auth + idempotency
- returns accepted scaffold response
- duplicate key returns the original response payload
4. Success `200` example:
```json
{
"accepted": true,
"route": "/commands/orders/create",
"commandId": "/commands/orders/create:173...",
"idempotencyKey": "client-key-123",
"requestId": "uuid"
}
```
## 6) Frontend fetch examples (web)
## 6.1 Signed URL request
## 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', {
@@ -160,7 +137,7 @@ const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/crea
const data = await res.json();
```
## 6.2 Model request
## 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', {
@@ -181,7 +158,7 @@ const res = await fetch('https://krow-core-api-e3g6witsvq-uc.a.run.app/core/invo
const data = await res.json();
```
## 7) Notes for frontend team
## 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.