Komplet teknisk reference for Ressourcify API v1 — alle endpoints, request/response-formater og adgangskrav.

Ressourcify v2 — API Reference

Version: v1 · Base path: /api/v1 · Sidst opdateret: 2026-04-23

1. Overblik

Alle API-endpoints ligger under /api/v1/. API'et er multi-tenant: hver request scoperes automatisk til den autentificerede brugers organisation.

Request-format: Content-Type: application/json Response-format: Content-Type: application/json (fejl: application/problem+json)

2. Konventioner

2.1 Autentificering

Alle /api/v1/-endpoints kræver en aktiv session. Autentificering håndteres af NextAuth v5 (Microsoft Entra ID / Azure AD). Uautentificerede requests modtager 401 Unauthorized.

Sessions vedligeholdes via en HTTP-only cookie (__Secure-next-auth.session-token). Der er ingen API-nøgle- eller Bearer-token-mekanisme.

2.2 Paginering

List-endpoints bruger cursor-baseret paginering:

{
  "data": [ /* array of items */ ],
  "nextCursor": "018e5f3a-..."
}

nextCursor er null når der ikke er flere sider. Send værdien som cursor-query-parameter for næste side.

Fælles query-parametre:

Parameter	Type	Standard	Maks
`cursor`	string	—	—
`limit`	integer	`50`	`200`

2.3 Fejlformat

Alle fejl følger RFC 7807 Problem Details:

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request body failed validation.",
  "errors": [
    { "field": "endDate", "message": "endDate must be on or after startDate" }
  ]
}

2.4 HTTP-statuskoder

Kode	Betydning
`200 OK`	Vellykket læsning eller opdatering
`201 Created`	Ressource oprettet
`204 No Content`	Vellykket sletning
`400 Bad Request`	Misdannet request
`401 Unauthorized`	Ingen gyldig session
`403 Forbidden`	Utilstrækkelig rolle
`404 Not Found`	Ressourcen eksisterer ikke
`409 Conflict`	Unique constraint-overtrædelse
`422 Unprocessable Entity`	Zod-valideringsfejl
`500 Internal Server Error`	Uventet serverfejl

2.5 Roller og adgangskontrol

Rolle	Scope	Beskrivelse
`ORG_ADMIN`	Organisation	Fuld administrativ adgang
`DEPT_ADMIN`	Afdeling	Admin inden for egne afdelinger
`COORDINATOR`	Team	Kan administrere assignments for egne teams
`RESOURCE`	Selv	Kan læse og skrive egne data
`VIEWER`	Organisation	Skrivebeskyttet adgang

2.6 Soft delete

Users — DELETE sætter deletedAt og skifter status til INACTIVE
Projects — DELETE sætter deletedAt og skifter status til CANCELLED

Soft-slettede poster ekskluderes automatisk fra alle list-responses.

3. Ressourcer

3.1 Users

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/users`	List brugere	`VIEWER`
`POST`	`/api/v1/users`	Opret bruger	`ORG_ADMIN`
`GET`	`/api/v1/users/:id`	Hent enkelt bruger	`VIEWER`
`PATCH`	`/api/v1/users/:id`	Opdatér bruger	`ORG_ADMIN`
`DELETE`	`/api/v1/users/:id`	Soft-slet bruger	`ORG_ADMIN`
`GET`	`/api/v1/users/export`	Download CSV	`DEPT_ADMIN`

GET /api/v1/users

Query-parametre: teamId, departmentId, status (ACTIVE|INACTIVE), q (fritekst, maks 80)

Eksempel-response:

{
  "data": [
    {
      "id": "018e5f3a-1111-7000-8000-000000000001",
      "name": "Anna Andersen",
      "email": "anna.andersen@demo.ressourcify.local",
      "status": "ACTIVE",
      "employmentPct": 1.0,
      "defaultWeeklyHours": 37,
      "startDate": "2024-01-01",
      "endDate": null,
      "primaryDepartmentId": "018e5f3a-2222-7000-8000-000000000001",
      "primaryDepartment": { "id": "018e5f3a-2222-7000-8000-000000000001", "name": "Design" },
      "teams": [
        { "teamId": "018e5f3a-3333-7000-8000-000000000001", "isCoordinator": true, "team": { "name": "Team Alpha", "color": "#3B82F6" } }
      ]
    }
  ],
  "nextCursor": null
}

Felt	Type	Påkrævet
`name`	string (1–120)	Ja
`email`	email	Ja — unik i org
`primaryDepartmentId`	UUID	Nej
`employmentPct`	number (0.1–1)	Nej — standard: `1`
`defaultWeeklyHours`	number (1–80)	Nej — standard: `37`
`startDate`	`YYYY-MM-DD`	Nej
`endDate`	`YYYY-MM-DD`	Nej
`status`	`ACTIVE`\|`INACTIVE`	Nej — standard: `ACTIVE`

PATCH /api/v1/users/:id

Alle POST-felter er valgfrie. Kun angivne felter opdateres.

DELETE /api/v1/users/:id

204 No Content. Brugeren soft-slettes.

GET /api/v1/users/export

Streamer UTF-8 CSV med BOM. Query-parametre: status, departmentId.

3.2 Departments

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/departments`	List afdelinger	`VIEWER`
`POST`	`/api/v1/departments`	Opret afdeling	`ORG_ADMIN`
`GET`	`/api/v1/departments/:id`	Hent enkelt	`VIEWER`
`PATCH`	`/api/v1/departments/:id`	Opdatér	`ORG_ADMIN`
`DELETE`	`/api/v1/departments/:id`	Slet	`ORG_ADMIN`

DEPT_ADMIN og COORDINATOR ser kun afdelinger de tilhører. En afdeling med aktive brugere kan ikke slettes — API'et returnerer 409 Conflict.

POST body: name (string 1–80, påkrævet), code (string maks 20, valgfri)

3.3 Teams

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/teams`	List teams	`VIEWER`
`POST`	`/api/v1/teams`	Opret team	`ORG_ADMIN`
`GET`	`/api/v1/teams/:id`	Hent enkelt	`VIEWER`
`PATCH`	`/api/v1/teams/:id`	Opdatér team og medlemmer	`ORG_ADMIN`
`DELETE`	`/api/v1/teams/:id`	Deaktivér	`ORG_ADMIN`

Query-parametre: q (fritekst), isActive (boolean)

POST body:

Felt	Type	Påkrævet
`name`	string (1–80)	Ja
`description`	string (maks 500)	Nej
`color`	hex-farve	Nej — standard: `#3B82F6`
`isActive`	boolean	Nej — standard: `true`
`members[].userId`	UUID	Ja
`members[].isCoordinator`	boolean	Nej — standard: `false`

members-arrayet i en PATCH-request erstatter hele medlemslisten. Udelades members, forbliver medlemmerne uændrede.

3.4 Projects

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/projects`	List projekter	`VIEWER`
`POST`	`/api/v1/projects`	Opret projekt	`COORDINATOR`
`GET`	`/api/v1/projects/:id`	Hent enkelt	`VIEWER`
`PATCH`	`/api/v1/projects/:id`	Opdatér	`COORDINATOR`
`DELETE`	`/api/v1/projects/:id`	Soft-slet	`ORG_ADMIN`

Query-parametre: status, deptId, teamId, q

POST body (udvalgte felter):

Felt	Type	Påkrævet
`code`	string (1–40)	Ja — konverteres til store bogstaver; unik i org
`name`	string (1–120)	Ja
`status`	`ACTIVE`\|`PAUSED`\|`COMPLETED`\|`CANCELLED`	Nej — standard: `ACTIVE`
`departmentId`, `managerId`, `categoryId`	UUID	Nej
`startDate`, `endDate`	`YYYY-MM-DD`	Nej
`forecastEnabled`	boolean	Nej — standard: `false`
`teamIds`	UUID[]	Nej — standard: `[]`

3.5 Assignments

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/assignments`	List assignments	`VIEWER`
`POST`	`/api/v1/assignments`	Opret	`COORDINATOR`
`GET`	`/api/v1/assignments/:id`	Hent enkelt	`VIEWER`
`PATCH`	`/api/v1/assignments/:id`	Opdatér	`COORDINATOR`
`DELETE`	`/api/v1/assignments/:id`	Slet	`COORDINATOR`

Query-parametre: projectId, userId, from, to (YYYY-MM-DD)

POST body:

Felt	Type	Påkrævet
`projectId`, `userId`	UUID	Ja
`startDate`	`YYYY-MM-DD`	Ja — skal være ≤ `endDate`
`endDate`	`YYYY-MM-DD`	Ja
`allocationKind`	`PERCENT`\|`HOURS`	Ja
`value`	number (0–999999)	Ja — hvis `PERCENT`, maks 100
`note`	string (maks 500)	Nej

3.6 Time Entries

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/time-entries`	List	`RESOURCE`
`POST`	`/api/v1/time-entries`	Opret	`RESOURCE`
`GET`	`/api/v1/time-entries/:id`	Hent enkelt	`RESOURCE`
`PATCH`	`/api/v1/time-entries/:id`	Opdatér	`RESOURCE`
`DELETE`	`/api/v1/time-entries/:id`	Slet	`RESOURCE`
`POST`	`/api/v1/time-entries/autofill`	Generer fra assignments	`COORDINATOR`

Self-scope: RESOURCE kan kun tilgå egne poster. COORDINATOR og derover kan tilgå alle i org. Kun hours og note kan opdateres via PATCH — date, projectId, userId og kind er uforanderlige.

POST /autofill query-parametre: userId, year, month, kind (standard: PLANNED)

Autofill-response: { "created": 12, "skipped": 8 }

3.7 Leaves

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/leaves`	List fravær	`RESOURCE`
`POST`	`/api/v1/leaves`	Opret	`COORDINATOR`
`GET`	`/api/v1/leaves/:id`	Hent enkelt	`RESOURCE`
`PATCH`	`/api/v1/leaves/:id`	Opdatér	`COORDINATOR`
`DELETE`	`/api/v1/leaves/:id`	Slet	`COORDINATOR`

RESOURCE kan kun se eget fravær.

POST body: userId, leaveTypeId (UUID), startDate, endDate, hoursPerDay (0.25–24, standard: brugerens daglige timer), note

3.8 Lookups

Organisationsstyrede referencelister. type-parametret vælger liste.

Typer: category, task-type, project-type, leave-type

Metode	Sti	Min. Rolle
`GET`	`/api/v1/lookups?type=`	`VIEWER`
`POST`	`/api/v1/lookups?type=`	`ORG_ADMIN`
`GET`	`/api/v1/lookups/:id?type=`	`VIEWER`
`PATCH`	`/api/v1/lookups/:id?type=`	`ORG_ADMIN`
`DELETE`	`/api/v1/lookups/:id?type=`	`ORG_ADMIN`

Elementer med organizationId: null er system-leverede og skrivebeskyttede. Hvis et element refereres af eksisterende poster, deaktiverer DELETE det i stedet for at fjerne det.

GET returnerer et fuldt array (ikke pagineret). Ekstra query-parameter: includeInactive (boolean, standard: false).

3.9 Capacity

Metode	Sti	Min. Rolle
`GET`	`/api/v1/capacity`	`RESOURCE`

Query-parametre: userId, year, month (valgfri — udelades: alle 12 måneder)

Response-felter:

Felt	Beskrivelse
`workdays`	Arbejdsdage (ekskl. weekender og helligdage)
`baseHours`	`workdays × defaultWeeklyHours / 5`
`leaveHours`	Fraværstimer trukket fra base
`netHours`	`baseHours − leaveHours`

3.10 Utilization

Metode	Sti	Min. Rolle
`GET`	`/api/v1/utilization`	`VIEWER`

Query-parametre: scope (user:<UUID> eller dept:<UUID>), from, to (YYYY-MM)

3.11 Forecast

Metode	Sti	Beskrivelse	Min. Rolle
`GET`	`/api/v1/forecast/plans`	List planer	`VIEWER`
`POST`	`/api/v1/forecast/plans`	Opret plan	`COORDINATOR`
`GET`	`/api/v1/forecast/plans/:id`	Hent enkelt	`VIEWER`
`PATCH`	`/api/v1/forecast/plans/:id`	Opdatér	`COORDINATOR`
`DELETE`	`/api/v1/forecast/plans/:id`	Slet	`COORDINATOR`
`GET`	`/api/v1/forecast/workloads`	Aggregerede timer	`VIEWER`

Kun én forecast-plan pr. (projectId, year) er tilladt. Duplikat returnerer 409 Conflict.

POST body: projectId, year, size (S|M|L|XL|F|T), startMonth, endMonth, note, teamIds, allocations[]

3.12 Rapporter og eksporter

Endpoint	Beskrivelse	Min. Rolle
`GET /api/v1/reports/workloads`	Udnyttelsesaggregat med totaler	`VIEWER`
`GET /api/v1/reports/opslag`	Årligt kapacitets-/udnyttelsessnapshot	`VIEWER`
`GET /api/v1/exports/totals`	CSV-eksport kapacitet + udnyttelse	`DEPT_ADMIN`

workloads query-parametre: from (YYYY-MM), to (YYYY-MM), scope (org, user:<UUID>, dept:<UUID>)

opslag query-parametre: year, teamId

totals query-parametre: period (YYYY-MM..YYYY-MM), format (csv)

preview-arrayet i response er kun til stede når dryRun: true.

4. System-endpoints

GET /api/health

Returnerer applikationens sundhedsstatus. Kræver ikke autentificering.

{ "status": "ok", "db": "ok", "version": "2.0.0" }

Hvis DB-forbindelsen fejler: db: "error" og HTTP 503.

GET + POST /api/auth/[...nextauth]

NextAuth.js-handler til Microsoft Entra ID-flow. Ikke beregnet til direkte brug af API-klienter.

API-reference v1