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:

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:

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:

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

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

Helse og innlogging

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

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:

{ "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

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

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

Oppgaver

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:

{
  "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

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

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 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.