On-Call Scheduling

⚠️ Preview — not yet in the public API

The endpoints on this page are part of the AurionAI helpdesk and are currently accessible only through an authenticated dashboard session. They are not yet exposed through public API keys — a request authenticated with X-API-Key returns 403. Public API-key access is planned. The reference below documents the intended contract.

On-Call Scheduling

The On-Call API (v2) lets you manage on-call schedules for support teams. Define rotations, manage shift entries, and query who's currently on call.

These endpoints require the Aurion CS platform profile and are authorized by your dashboard session (a tenant-JWT with one of the roles super_admin, tenant_owner, or tenant_admin — the read-only GET /current/{team_id} lookup additionally allows agent, supervisor, tenant_user, and tenant_readonly). They are not gated by API-key scopes — there is no oncall scope, and a request authenticated with X-API-Key is rejected with 403. The X-API-Key examples below show the intended future public-API contract.

List Schedules

Optionally filter by team with the ?team_id= query parameter (the only supported query param).

curl "https://apps.aurionai.net/api/v2/oncall/schedules?team_id=team_789" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

Returns a bare JSON array of schedule objects (no pagination envelope).

[
  {
    "id": "sched_abc123",
    "team_id": "team_789",
    "name": "After-Hours Network Support",
    "timezone": "Europe/Brussels",
    "rotation_type": "weekly",
    "is_active": true,
    "created_at": "2026-02-01T10:00:00Z",
    "updated_at": "2026-02-01T10:00:00Z"
  }
]

Create Schedule

team_id and name are required. name must be 1–100 chars; timezone (max 50 chars) defaults to "UTC" and rotation_type (max 20 chars) defaults to "weekly". Returns 201 Created with the created schedule object.

curl -X POST "https://apps.aurionai.net/api/v2/oncall/schedules" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "team_id": "team_789",
    "name": "Weekend Support",
    "timezone": "Europe/Brussels",
    "rotation_type": "weekly"
  }'

Get Schedule

curl "https://apps.aurionai.net/api/v2/oncall/schedules/sched_abc123" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 404 with {"detail": "Schedule not found"} for an unknown id.

Update Schedule

Partial update — only the fields you send are changed. Accepts name, timezone, rotation_type, and is_active.

curl -X PATCH "https://apps.aurionai.net/api/v2/oncall/schedules/sched_abc123" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "After-Hours Network Support (Updated)",
    "timezone": "Europe/Paris"
  }'

Delete Schedule

curl -X DELETE "https://apps.aurionai.net/api/v2/oncall/schedules/sched_abc123" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content on success, or 404 {"detail": "Schedule not found"} if the id is unknown.

Schedule Entries

Entries are individual shifts within a schedule.

Note the path asymmetry: listing and creating entries are nested under a schedule (/schedules/{schedule_id}/entries), while swapping and deleting an entry use the flat top-level path (/entries/{entry_id}).

An entry object has these fields:

{
  "id": "entry_456",
  "schedule_id": "sched_abc123",
  "user_id": "user_012",
  "user_email": "marie@example.com",
  "user_name": "Marie Laurent",
  "start_at": "2026-03-15T18:00:00+01:00",
  "end_at": "2026-03-16T08:00:00+01:00",
  "replaced_by_user_id": null,
  "replaced_by_name": null,
  "created_at": "2026-03-01T09:00:00Z"
}

List Entries

Takes no query parameters — it returns all entries for the schedule as a bare JSON array of entry objects.

curl "https://apps.aurionai.net/api/v2/oncall/schedules/sched_abc123/entries" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Create Entry

Returns 201 Created with the created entry. Validation errors (e.g. overlapping shifts) return 400 {"detail": "<message>"}; an unknown schedule or user reference returns 422 {"detail": "Invalid reference (schedule or user not found)"}.

curl -X POST "https://apps.aurionai.net/api/v2/oncall/schedules/sched_abc123/entries" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "user_012",
    "start_at": "2026-03-15T18:00:00+01:00",
    "end_at": "2026-03-16T08:00:00+01:00"
  }'

Swap Entry

Replace the on-call user for an existing entry. This sets replaced_by_user_id on the single entry you reference — it is a per-entry replacement, not a two-shift exchange. Returns 200 with the updated entry object (the replaced_by_user_id / replaced_by_name fields reflect the new user).

curl -X POST "https://apps.aurionai.net/api/v2/oncall/entries/entry_456/swap" \
  -H "X-API-Key: itsm_sk_live_xxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "replaced_by_user_id": "user_034"
  }'

Response:

{
  "id": "entry_456",
  "schedule_id": "sched_abc123",
  "user_id": "user_012",
  "user_email": "marie@example.com",
  "user_name": "Marie Laurent",
  "start_at": "2026-03-15T18:00:00+01:00",
  "end_at": "2026-03-16T08:00:00+01:00",
  "replaced_by_user_id": "user_034",
  "replaced_by_name": "Tom Janssen",
  "created_at": "2026-03-01T09:00:00Z"
}

Delete Entry

curl -X DELETE "https://apps.aurionai.net/api/v2/oncall/entries/entry_456" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Returns 204 No Content on success, or 404 {"detail": "Entry not found"} if the id is unknown.

Who's On Call Now?

Get the current on-call person for a team. Returns a flat object; 404 {"detail": "No active on-call found for this team"} when nobody is currently on call.

curl "https://apps.aurionai.net/api/v2/oncall/current/team_789" \
  -H "X-API-Key: itsm_sk_live_xxxx"

Response:

{
  "user_id": "user_012",
  "user_email": "marie@example.com",
  "user_name": "Marie Laurent",
  "schedule_name": "After-Hours Network Support",
  "entry_id": "entry_456"
}

Rotation Types

rotation_type is a free-form string (max 20 chars) — it is not a validated enum, so any string within the length limit is accepted. The values below are conventions used by the dashboard UI, not enforced by the API:

Related Guides

• Teams & Routing — Team management and business hours
• Notifications — On-call notification preferences