# Nxtly REST API v1

Baseadresse: `https://api.nxtly.app/v1`

API-et svarer med JSON. Dokumentasjonssidene bruker HTML eller ren tekst.
Vellykkede svar har `{ "success": true, "data": ... }`; feil har
`{ "success": false, "error": { "code", "message", "fields?" } }`.
Alle autentiserte svar sendes med `Cache-Control: no-store`.

## Kom i gang

Åpne **Innstillinger → Integrasjoner → API-nøkler** i den oppdaterte Apple-appen,
eller **Konto → Integrasjoner og API-nøkler** på nett. Velg arbeidsområde,
gi nøkkelen et navn, velg rettigheter og utløpstid, og kopier nøkkelen.
Hele nøkkelen vises bare én gang. Du må være eier eller administrator for å
administrere nøkler.

Du kan velge ditt personlige arbeidsområde og delte prosjekter du administrerer.
Arbeidsområde-ID-en som vises, brukes som `X-Workspace` nedenfor.
API-nøkler gir ikke tilgang til notater; bruk en MCP-tilkobling med OAuth for det.

Sett `NXTLY_API_KEY` til nøkkelen og `NXTLY_WORKSPACE` til arbeidsområdets UUID
i integrasjonens konfigurasjon for hemmeligheter. Hent for eksempel åpne oppgaver:

```bash
curl 'https://api.nxtly.app/v1/todos?status=open&sort=due&limit=20' \
  -H "Authorization: Bearer $NXTLY_API_KEY" \
  -H "X-Workspace: $NXTLY_WORKSPACE"
```

Opprett en oppgave med en nøkkel som har `tasks:write`:

```bash
curl 'https://api.nxtly.app/v1/todos' \
  -H "Authorization: Bearer $NXTLY_API_KEY" \
  -H "X-Workspace: $NXTLY_WORKSPACE" \
  -H 'Content-Type: application/json' \
  --data '{"title":"Send tilbudet","priority":"high"}'
```

Tilbakekall nøkkelen i samme innstillingsbilde for å stoppe tilgangen umiddelbart.
Utløpte og tilbakekalte nøkler kan ikke brukes igjen; opprett en ny nøkkel.

## Autentisering og prosjekttilgang

Bruk `Authorization: Bearer <access-token>` for brukerøkter. Varige MCP- og
API-integrasjoner bør bruke en nøkkel bundet til et arbeidsområde i samme header:
`Authorization: Bearer nxtly_<64 heksadesimale tegn>`.

Prosjektspesifikke kall bruker `X-Workspace: <prosjektets UUID eller slug>`.
API-nøkler genereres kryptografisk tilfeldig, lagres bare som SHA-256-hash og kan
ikke brukes med andre arbeidsområder. Hele nøkkelen returneres bare ved oppretting.

Tilgjengelige rettigheter:

| Rettighet | Tilgang |
|---|---|
| `tasks:read` | Lese oppgaver, lister, etiketter og søke i prosjektet |
| `tasks:write` | Opprette, endre, fullføre, slette og gjenopprette oppgaver, lister og etiketter |
| `projects:read` | Lese prosjektinformasjon og medlemmer |
| `projects:write` | Endre eller slette et prosjekt; eierkrav gjelder fortsatt |
| `members:manage` | Lese, opprette og tilbakekalle invitasjoner samt endre og fjerne medlemmer |

Et brukertoken kan bruke hele API-et innenfor brukerens rettigheter. API-nøkler
har ikke tilgang til kontoprofil, innlogging, samlevisninger (`/combined`),
hendelser, aksept av invitasjoner, notater eller administrasjon av API-nøkler.

## Endepunkter

### Offentlig dokumentasjon

| Metode | Sti fra domenets rot | Formål |
|---|---|---|
| `GET` | `/docs` | Denne REST API-referansen |
| `GET` | `/docs/mcp` | MCP-veiledning og verktøyoversikt |
| `GET` | `/docs/api.md` | REST-referansen som Markdown |
| `GET` | `/docs/mcp.md` | MCP-veiledningen som Markdown |

Alle stier nedenfor er relative til `/v1`, med mindre noe annet er oppgitt.

### Helse og innlogging

| Metode | Sti | Formål |
|---|---|---|
| `GET` | `/health` | Helsesjekk som også kontrollerer databasen |
| `POST` | `/auth/register` | Opprette bruker, personlig arbeidsområde og økt |
| `POST` | `/auth/login` | Opprette en brukerøkt |
| `POST` | `/auth/refresh` | Rotere oppfriskningstoken og utstede et nytt tokenpar |
| `POST` | `/auth/logout` | Tilbakekalle et oppfriskningstoken |

Registrering tar imot `name`, `email` og `password`. Innlogging tar imot `email`,
`password` og valgfritt `device_name`. Oppfriskning og utlogging tar imot
`refresh_token`. Tilgangstokener er kortvarige. Oppfriskningstokener roteres og
må erstattes etter hver vellykkede oppfriskning.

### Bruker, prosjekter og samarbeid

| Metode | Sti | Formål |
|---|---|---|
| `GET` | `/me` | Hente innlogget brukers profil |
| `PATCH` | `/me` | Endre navn, innstillinger eller passord |
| `GET` | `/me/workspaces` | Hente personlige og delte arbeidsområder med akseptert medlemskap |
| `GET` | `/projects` | Hente tilgjengelige delte prosjekter |
| `POST` | `/projects` | Opprette et delt prosjekt |
| `GET` | `/projects/{project_id}` | Hente prosjekt, egen rolle og antall medlemmer |
| `PATCH` | `/projects/{project_id}` | Endre navn på et prosjekt du eier |
| `DELETE` | `/projects/{project_id}` | Slette et delt prosjekt du eier permanent |
| `GET` | `/projects/{project_id}/members` | Hente medlemmer og roller |
| `PATCH` | `/projects/{project_id}/members/{user_id}` | Endre rolle |
| `DELETE` | `/projects/{project_id}/members/{user_id}` | Fjerne medlem eller forlate prosjektet |
| `GET` | `/projects/{project_id}/invitations` | Hente ventende invitasjoner som administrator |
| `POST` | `/projects/{project_id}/invitations` | Invitere via e-post og returnere privat delingslenke |
| `DELETE` | `/projects/{project_id}/invitations/{invitation_id}` | Tilbakekalle invitasjon |
| `GET` | `/invitations` | Hente ventende invitasjoner for innlogget e-postadresse |
| `POST` | `/invitations/accept` | Godta et invitasjonstoken på 64 tegn |

`POST /workspaces`, `PATCH /workspaces/{project_id}` og
`DELETE /workspaces/{project_id}` beholdes som aliaser for eldre klienter.

Prosjektrollene er `owner`, `admin`, `member` og `guest`. Eiere og administratorer
administrerer medlemmer. Medlemmer oppretter og endrer delte oppgaver. Gjester
har lesetilgang og ser bare oppgaver med `visibility: "guests"` eller oppgaver
som er tildelt dem. Bare den som opprettet oppgaven, eller en administrator,
kan slette, gjenopprette eller endre synligheten til oppgaven.

Opprett en invitasjon med:

```json
{ "email": "person@example.com", "role": "member" }
```

Svaret inneholder `token`, `share_url` og `expires_at`. Tokenet vises bare i dette
svaret, lagres som hash, utløper etter sju dager og er bundet til den inviterte
e-postadressen. Det kan ikke brukes etter aksept eller tilbakekalling.

### API-nøkler

| Metode | Sti | Formål |
|---|---|---|
| `GET` | `/api-keys` | Liste nøkler uten selve hemmeligheten |
| `POST` | `/api-keys` | Opprette nøkkel for ett arbeidsområde; hele nøkkelen returneres én gang |
| `DELETE` | `/api-keys/{key_id}` | Tilbakekalle nøkkel umiddelbart |

Disse endepunktene krever brukertoken, `X-Workspace` og rollen eier eller administrator.

```json
{
  "name": "MCP på min Mac",
  "scopes": ["tasks:read", "tasks:write", "projects:read"],
  "expires_at": "2027-09-05T12:00:00Z"
}
```

### Oppgaver

| Metode | Sti | Formål |
|---|---|---|
| `GET` | `/todos` | Liste synlige oppgaver i arbeidsområdet |
| `POST` | `/todos` | Opprette en oppgave |
| `GET` | `/todos/{task_id}` | Hente én synlig oppgave |
| `PATCH` | `/todos/{task_id}` | Endre oppgitte felt eller fullføre oppgaven |
| `DELETE` | `/todos/{task_id}` | Flytte oppgaven til papirkurven |
| `POST` | `/todos/{task_id}/restore` | Gjenopprette oppgaven |

Listekallet støtter `list_id`, `status`, `priority`, `parent_id`, `tag`,
`assignee` (`me` eller brukerens UUID), `sort` (`created`, `updated`, `due`,
`priority`, `title`), `limit` (1–100) og heltallet `cursor` som spørringsparametere.

En oppgave kan sendes slik:

```json
{
  "title": "Publiser ny versjon",
  "description": "Siste gjennomgang og publisering",
  "status": "pending",
  "priority": "high",
  "visibility": "team",
  "assignee_ids": ["bruker-uuid-1", "bruker-uuid-2"],
  "list_id": null,
  "parent_id": null,
  "tags": ["etikett-uuid"],
  "due_date": "2027-03-01T09:00:00Z",
  "reminder_at": "2027-03-01T08:30:00Z",
  "location": "Oslo",
  "visible_from": "2027-02-20",
  "recurrence": { "interval_days": 7 }
}
```

Statusverdiene er `pending`, `in_progress` og `done`. Prioritet er `low`, `medium`,
`high` eller `urgent`. Synlighet er `private`, `team` eller `guests`.
`assignee_ids` støtter opptil 100 aksepterte prosjektmedlemmer. Det eldre feltet
`assignee_id` støttes fortsatt. Svaret inkluderer `created_by` og hele listen
`assignees`. Når en gjentakende oppgave fullføres, flyttes den frem til neste
gjentakelse og venter til neste `visible_from`-dato.

### Lister, etiketter, mapper og notater

| Metode | Sti | Formål |
|---|---|---|
| `GET`, `POST` | `/lists` | Liste eller opprette oppgavelister |
| `GET`, `PATCH`, `DELETE` | `/lists/{list_id}` | Hente, endre eller slette en liste |
| `GET`, `POST` | `/tags` | Liste eller opprette etiketter |
| `PATCH`, `DELETE` | `/tags/{tag_id}` | Endre eller slette en etikett |
| `GET`, `POST` | `/folders` | Liste eller opprette notatmapper |
| `GET`, `PATCH`, `DELETE` | `/folders/{folder_id}` | Hente, endre eller slette en mappe |
| `GET`, `POST` | `/notes` | Liste eller opprette notater |
| `GET`, `PATCH`, `DELETE` | `/notes/{note_id}` | Hente, endre eller flytte notat til papirkurven |
| `POST` | `/notes/{note_id}/restore` | Gjenopprette et notat |

Lister støtter `name`, `color`, `icon`, `sort_order` og de samme tre verdiene for
synlighet som oppgaver. Notater og mapper er private for den som opprettet dem;
prosjektsamarbeid gjelder foreløpig oppgavelister og oppgaver.

### Søk, samlevisninger og sanntidsoppdateringer

| Metode | Sti | Formål |
|---|---|---|
| `GET` | `/search?q=...&limit=...` | Søke i synlige oppgaver og private notater i aktivt arbeidsområde |
| `GET` | `/combined/search?q=...&limit=...` | Søke på tvers av arbeidsområder med akseptert medlemskap |
| `GET` | `/combined/todos` | Hente synlige oppgaver på tvers av arbeidsområder |
| `GET` | `/combined/notes` | Hente private notater på tvers av arbeidsområder |
| `GET` | `/combined/sidebar` | Hente arbeidsområder, lister og mapper som trestruktur |
| `POST` | `/events/token` | Bytte brukertoken mot kortvarig token for hendelsesstrøm |
| `GET` | `/events?token=...` | Motta endringssignaler med Server-Sent Events |

## MCP

Den eksterne MCP-serveren ligger på `https://api.nxtly.app/v1/mcp` og støtter
innlogging med OAuth. Den lokale stdio-serveren støtter API-nøkler.
Se [MCP-veiledningen](../mcp/README.md) for oppsett og verktøyoversikt.

## Synkronisering av lokal cache

`POST /v1/sync` krever en bruker-JWT. API-nøkler og MCP OAuth-tokener kan ikke
lese øyeblikksbildet for hele kontoen. Send `{ "changes": [...] }` med maksimalt
128 poster og en forespørsel på høyst 1 MB. En tom liste henter gjeldende
øyeblikksbilde og servertid.

Poster inneholder `kind` (`company`, `project`, `note`, `task`), UUID `id`,
`modified_us` (opprinnelig handlingstid i mikrosekunder siden Unix-epoken, UTC),
UUID `operation_id`, `deleted` og `data`. Svaret inneholder `records` (hele det
autoriserte øyeblikksbildet), `acknowledged` (operasjons-ID-er) og `server_time_us`.
Gjentatte forsøk beholder opprinnelig tid og operasjons-ID. Ved konflikt vinner
høyeste tidsstempel, deretter leksikografisk høyeste operasjons-ID. Sletting
beholder en slettemarkør. Versjoner gjelder hele posten.

Prosjektreferanser bruker UUID. Et prosjekt satt til `null` betyr personlig
arbeidsområde. Oppgaver bruker `title`, `detail`, `status` (`backlog`, `doing`,
`done`), `priority` (0–2), valgfritt `project_id`, `note_id`, `source_key`,
`due_at_us` og `created_at_us`. Notater bruker `title`, `markdown`, `pinned`,
`project_id` og `created_at_us`. Prosjekter bruker `name`, `summary`, `symbol`,
`archived`, `company_id` og `created_at_us`. Selskaper bruker `name`, `summary`
og `created_at_us`.

REST-endringer av oppgaver kan inkludere `_action_time_us` og `_operation_id`
for å sende handlinger utført uten nett. Oppretting kan også inkludere `_record_id`
for trygt å gjenta et kall der svaret gikk tapt. Uten disse feltene bruker
REST og MCP servertiden. Svar inneholder `X-Server-Time-Us` for kalibrering av
enhetens klokke. Tidsstempler mer enn fem minutter frem i tid avvises.

Øyeblikksbildet inkluderer valgfritt `can_edit` på delte poster og `can_add` på
prosjekter. Klienter kan bruke dette til å deaktivere redigering uten å endre
medlemsrettigheter.

## Tilbakestilling av passord

- `POST /v1/auth/forgot-password` med `{email}`: 202 med samme svar for kjente og ukjente kontoer. Gir 503 når e-postsending ikke er konfigurert, eller 429 ved rategrense.
- `POST /v1/auth/reset-password` med `{token,password}`: 200 etter én gangs bruk innen 30 minutter. Ugyldig, utløpt eller brukt token gir 400. Passord krever minst 8 tegn og maksimalt 72 byte.
- Nytt passord tilbakekaller innloggingsøkter, oppfriskningstokener og OAuth-tilkoblinger umiddelbart. Brukeren må logge inn igjen.