a308041d59
FamilyNido — a self-hosted PWA for a single household: shared calendar, chores, meals, school agenda, health records and a family wall. One instance per family, deployable with `docker compose` on any home server. Stack: .NET 10 (ASP.NET Core Minimal APIs) + EF Core 10 + PostgreSQL 16 on the backend, Angular 21 (standalone, signals, zoneless) + Tailwind CSS v4 on the frontend, SignalR for realtime, optional OIDC alongside local credentials, integration via a versioned `/api/v1/**` public API. See README.md for the module overview and how to deploy.
66 lines
2.2 KiB
Markdown
66 lines
2.2 KiB
Markdown
# Integrations — FamilyNido public API
|
||
|
||
FamilyNido exposes a small set of versioned endpoints under `/api/v1/**`
|
||
so any external integration (an automation runner, n8n, IFTTT, a cron
|
||
job on another machine…) can create tasks in the family's dashboard.
|
||
|
||
Authentication is by **API key**, minted from the FamilyNido admin UI
|
||
(*My account → API keys for integrations*, admins only). The key is
|
||
sent with every request:
|
||
|
||
```
|
||
X-Api-Key: bxn_xxxxxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
or, alternatively, as `Authorization: Bearer bxn_…`.
|
||
|
||
## Available endpoints
|
||
|
||
### `POST /api/v1/tasks` — create a task
|
||
|
||
Body (JSON):
|
||
|
||
| Field | Type | Required | Default | Notes |
|
||
| - | - | - | - | - |
|
||
| `title` | string | yes | — | Up to 200 characters. |
|
||
| `category` | string | no | `"General"` | Up to 50 characters. |
|
||
| `points` | int | no | `5` | Range 0–100. |
|
||
| `dueDate` | string `YYYY-MM-DD` | no | today | Ignored when `isFloating=true`. |
|
||
| `isFloating` | bool | no | `false` | Floating task — has no fixed date and stays pending every day until someone marks it done. |
|
||
| `responsibleMemberId` | guid | no | — | Must belong to the family the token was issued for. |
|
||
| `deduplicate` | bool | no | `false` | When `true` and a pending task (not archived, no completions) with the same `title` already exists, returns `200 OK` with `created=false` instead of inserting a new row. |
|
||
|
||
Response `201 Created` (or `200 OK` when `deduplicate` matches an
|
||
existing pending task):
|
||
|
||
```json
|
||
{
|
||
"created": true,
|
||
"reason": null,
|
||
"taskId": "01938efc-...",
|
||
"title": "Empty the dishwasher"
|
||
}
|
||
```
|
||
|
||
`reason` is `"already-pending"` on a dedup hit.
|
||
|
||
Common errors:
|
||
|
||
- `400 Bad Request`: validation failed (empty title, `points` out of
|
||
range, `responsibleMemberId` outside the family).
|
||
- `401 Unauthorized`: header missing, malformed or revoked.
|
||
- `429 Too Many Requests`: rate limit exceeded (60 req/min/IP).
|
||
|
||
### Example: `curl`
|
||
|
||
```bash
|
||
curl -X POST https://your-host/api/v1/tasks \
|
||
-H "X-Api-Key: bxn_xxxxxxxx…" \
|
||
-H "Content-Type: application/json" \
|
||
-d '{"title":"Buy bread","category":"Shopping","points":1}'
|
||
```
|
||
|
||
## Concrete guides
|
||
|
||
If you wire up an integration worth sharing, open a PR against this
|
||
folder with a short worked example — that kind of doc pays for itself.
|