# Roster SDK & API

The TypeScript SDK exposes roster management through three workspace namespaces:

| Namespace | Responsibility |
| --- | --- |
| `fivexer.roster` | Workspace setup: rules, pay, terms, sites, posts, bands, templates, and coverage |
| `fivexer.rosters` | Planning periods: drafts, assignments, lint, solving, publishing, and cover |
| `fivexer.timeOff` | Time-off requests, impact, approval, and denial |

These methods are available through the `/v1` API-key client and the session-authenticated console data client. Use a workspace API key only in trusted server-side code; never ship it in a browser or worker app. See [authentication and keys](/docs/concepts/auth-and-keys/).

## Setup operations

```
tsfivexer.roster.settings()
fivexer.roster.setSettings(input)
fivexer.roster.pay()
fivexer.roster.setPay(input)
fivexer.roster.terms()
fivexer.roster.setTerms(workerId, input)
fivexer.roster.plannedHours({ from, to })
```

Coverage structure:

```
tsfivexer.roster.sites()
fivexer.roster.createSite(input)
fivexer.roster.updateSite(id, input)
fivexer.roster.deleteSite(id)

fivexer.roster.listStations()       // posts in the console
fivexer.roster.createStation(input)
fivexer.roster.updateStation(id, input)
fivexer.roster.deleteStation(id)

fivexer.roster.listBands()
fivexer.roster.createBand(input)
fivexer.roster.updateBand(id, input)
fivexer.roster.deleteBand(id)

fivexer.roster.coverage()
fivexer.roster.setCell(stationId, bandId, input)
fivexer.roster.clearCoverage()
```

Templates may also be managed directly with `listTemplates`, `createTemplate`, `updateTemplate`, and `deleteTemplate`. `startingPoints`, `applyPattern`, and `applySiteShape` support first-run setup; inspect the returned catalog rather than hard-coding starter IDs.

## Planning operations

```
tsfivexer.rosters.list({ from, to, teamId })
fivexer.rosters.create(input)
fivexer.rosters.get(id)
fivexer.rosters.versions(id)
fivexer.rosters.setAssignments(id, input)
fivexer.rosters.delete(id)
```

Read-only decision support:

```
tsfivexer.rosters.lint(id, input?)
fivexer.rosters.explain(id, { employeeId, shiftInstanceId })
fivexer.rosters.candidates(id, { shiftInstanceId })
fivexer.rosters.diagnose(id)
fivexer.rosters.publishPreflight(id)
```

Mutating planning operations:

```
tsfivexer.rosters.solve(id, input?)
fivexer.rosters.solveStatus(id)
fivexer.rosters.cancelSolve(id)
fivexer.rosters.publish(id, { versionId })
```

## Cover and time off

```
tsfivexer.rosters.reportCover(id, input)
fivexer.rosters.cover(id, query?)
fivexer.rosters.coverCandidates(id, coverId)
fivexer.rosters.fillCover(id, coverId, openingId, input)
fivexer.rosters.offerCover(id, coverId, openingId, input)
fivexer.rosters.dropCover(id, coverId, openingId)
fivexer.rosters.cancelCover(id, coverId)

fivexer.timeOff.list(query?)
fivexer.timeOff.create(input)
fivexer.timeOff.impact(id)
fivexer.timeOff.approve(id, input?)
fivexer.timeOff.deny(id, input?)
```

## Operational rules

- Treat roster versions as optimistic-concurrency tokens; send `baseVersion` when saving assignments.
- Poll solve jobs with `solveStatus`; a successful request to start solving is not a finished roster.
- Run `publishPreflight` immediately before `publish` and pass the reviewed `versionId`.
- Do not retry non-idempotent create, publish, fill, or offer calls blindly. Use the SDK’s error type and inspect status and code.
- Preserve stable shift occurrence IDs. Generate them from the returned roster detail rather than recreating dates client-side.
- Keep worker-facing access on worker or supervisor credentials. Workspace keys belong on trusted servers.

For the human workflow behind these calls, start with [build a roster](/docs/rostering/build/) and [validate and publish](/docs/rostering/publish/).