mirror of
https://github.com/System-End/nephthys.git
synced 2026-04-19 22:05:12 +00:00
a1f3ebfaf6
* Add a tickets API * Add more fields to JSON response for /api/ticket and /api/tickets * Prevent returning a massive number of tickets by default * Add an order to the query * Document /api/tickets
118 lines
3.5 KiB
Markdown
118 lines
3.5 KiB
Markdown
# Nephthys API docs
|
|
|
|
There is no proper API documentation (apart from [the code](https://github.com/hackclub/nephthys/blob/main/nephthys/utils/starlette.py)) yet, but
|
|
here's some explanation of the important routes.
|
|
|
|
All routes respond with JSON.
|
|
|
|
## `/api/stats_v2`
|
|
|
|
Statistics! Gives a bunch of metric-like statistic numbers so that you
|
|
can see how the support channel is doing.
|
|
|
|
Gives a response like:
|
|
|
|
```ts
|
|
interface StatsV2 {
|
|
all_time: OverallStats
|
|
past_24h: TimeBoundStats
|
|
past_24h_previous: TimeBoundStats
|
|
past_7d: TimeBoundStats
|
|
past_7d_previous: TimeBoundStats
|
|
}
|
|
|
|
interface OverallStats {
|
|
tickets_total: number
|
|
tickets_open: number
|
|
tickets_closed: number
|
|
tickets_in_progress: number
|
|
helpers_leaderboard: Array<LeaderboardEntry>
|
|
mean_hang_time_minutes_unresolved: number | null
|
|
mean_hang_time_minutes_all: number | null
|
|
mean_resolution_time_minutes: number | null
|
|
oldest_unanswered_ticket: OldestUnansweredTicket | null
|
|
}
|
|
|
|
interface TimeBoundStats {
|
|
/** Tickets created within the time period */
|
|
new_tickets_total: number
|
|
/** Tickets created within the time period and now closed */
|
|
new_tickets_now_closed: number
|
|
/** Tickets created within time period that are now open */
|
|
new_tickets_still_open: number
|
|
/** Tickets created within time period that are now in progress */
|
|
new_tickets_in_progress: number
|
|
/** Tickets closed within the time period */
|
|
closed_today: number
|
|
/** Tickets created and closed within the time period */
|
|
closed_today_from_today: number
|
|
/** Tickets assigned within the time period that are now in progress */
|
|
assigned_today_in_progress: number
|
|
/** Leaderboard for tickets closed within the time period */
|
|
helpers_leaderboard: Array<LeaderboardEntry>
|
|
/** Mean time to first helper response for tickets created within the time period that are currently unresolved */
|
|
mean_hang_time_minutes_unresolved: number | null
|
|
/** Mean time to first helper response for tickets created within the time period */
|
|
mean_hang_time_minutes_all: number | null
|
|
/** Mean time to resolution for tickets created within the time period */
|
|
mean_resolution_time_minutes: number | null
|
|
}
|
|
|
|
interface LeaderboardEntry {
|
|
id: number
|
|
slack_id: string
|
|
count: number
|
|
}
|
|
|
|
interface OldestUnansweredTicket {
|
|
id: number
|
|
created_at: string
|
|
age_minutes: number
|
|
link: string
|
|
}
|
|
```
|
|
|
|
Note that some fields can be `null` if there are no tickets (or no open/closed/in-progress tickets)
|
|
within the time period.
|
|
|
|
## `/api/tickets`
|
|
|
|
Returns a big list of tickets and their details! Please provide filters using query parameters
|
|
to avoid overloading Nephthys as it tries to provide 1,000s of tickets at once.
|
|
|
|
Parameters available are:
|
|
|
|
- `?status=` - filter by ticket status, can be `open`, `closed`, or `in_progress`
|
|
- `?since=` or `?after=` - filter for tickets created after a certain date/time, in ISO 8601 format (e.g. `2026-01-01`)
|
|
- `?until=` or `?before=` - filter for tickets created before a certain date/time, in ISO 8601 format (e.g. `2026-01-31T12:00:00`)
|
|
|
|
Returns an array of ticket objects. Ticket objects look like this:
|
|
|
|
```ts
|
|
interface Ticket {
|
|
id: number
|
|
title: string
|
|
description: string
|
|
status: "open" | "closed" | "in_progress"
|
|
opened_by: User | null
|
|
closed_by: User | null
|
|
assigned_to: User | null
|
|
reopened_by: User | null
|
|
tags: Array<string>
|
|
created_at: string
|
|
message_ts: string
|
|
}
|
|
|
|
interface User {
|
|
id: number
|
|
slack_id: string
|
|
}
|
|
```
|
|
|
|
## `/api/ticket?id=<TICKET_ID>`
|
|
|
|
Returns a single ticket! See above for details on the ticket object returned.
|
|
|
|
Required parameter:
|
|
|
|
- `?id=` - the ID of the ticket to return
|