{ "openapi": "3.1.0", "info": { "title": "Oncallz", "version": "1.0.0", "description": "REST API for the Oncallz on-call & incident management platform. Authenticate with `POST \/api\/login` to obtain a bearer token, then send it as `Authorization: Bearer ` on every request. All responses are JSON; IDs are UUIDv7 strings and timestamps are ISO-8601 UTC. See the narrative guide in docs\/API.md for end-to-end mobile flows." }, "servers": [ { "url": "https:\/\/oncallz.com\/api" } ], "security": [ { "http": [] } ], "paths": { "\/on-call\/current": { "get": { "operationId": "assignment.currentForTenant", "summary": "Everyone on call across the tenant **right now**, one entry per active\nschedule that currently has someone on call. Visibility follows\n{@see restrictToOwnTeams()}: the org-wide directory by default, the\ncaller's own teams when `?scope=mine` or the tenant has narrowed it.\nSingle query (no per-schedule lookups)", "tags": [ "Assignment" ], "responses": { "200": { "description": "Same swap the per-schedule view and the web dashboard do \u2014 without it\nthis list shows the rotation's pick while an override is live.\n\n\n\nArray of `AssignmentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AssignmentResource" } } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/schedules\/{schedule}\/on-call\/current": { "get": { "operationId": "assignment.current", "summary": "The user currently on call for the schedule", "tags": [ "Assignment" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "The schedule ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "anyOf": [ { "$ref": "#\/components\/schemas\/AssignmentResource" }, { "type": "null" } ] } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/schedules\/{schedule}\/on-call\/upcoming": { "get": { "operationId": "assignment.upcoming", "summary": "Upcoming assignments, soonest first", "tags": [ "Assignment" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "The schedule ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `AssignmentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AssignmentResource" } } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/schedules\/{schedule}\/on-call\/history": { "get": { "operationId": "assignment.history", "summary": "Past assignments, most recent first", "tags": [ "Assignment" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "The schedule ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Array of `AssignmentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/AssignmentResource" } } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/auth\/login": { "post": { "operationId": "auth.login", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "password": { "type": "string" }, "tenant_slug": { "type": [ "string", "null" ], "description": "Optional disambiguator: emails are unique per tenant, not globally." } }, "required": [ "email", "password" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "string" } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" } }, "security": [] } }, "\/auth\/refresh": { "post": { "operationId": "auth.refresh", "summary": "Exchange a valid refresh token for a fresh access + refresh pair. The\nroute is guarded by `ability:refresh`, so only refresh tokens reach here", "tags": [ "Auth" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "token_type": { "type": "string", "const": "Bearer" }, "access_token": { "type": "string" }, "refresh_token": { "type": "string" }, "expires_in": { "type": "string" } }, "required": [ "token_type", "access_token", "refresh_token", "expires_in" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/auth\/me": { "get": { "operationId": "auth.me", "tags": [ "Auth" ], "responses": { "200": { "description": "`UserResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/auth\/logout": { "post": { "operationId": "auth.logout", "summary": "Revoke the current device's token pair (its whole family)", "tags": [ "Auth" ], "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Logged out." } }, "required": [ "message" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/devices": { "post": { "operationId": "device.store", "summary": "Register (or update) the caller's device token. Idempotent by token", "tags": [ "Device" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "$ref": "#\/components\/schemas\/StoreDeviceTokenRequest" } } } }, "responses": { "200": { "description": "`DeviceTokenResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/DeviceTokenResource" } }, "required": [ "data" ] } } } }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" } } }, "delete": { "operationId": "device.destroy", "summary": "Unregister a device token (call on logout). Token in the request body", "tags": [ "Device" ], "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 512 } } ], "responses": { "204": { "description": "No content" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/incidents": { "get": { "operationId": "incident.index", "description": "Filters: ?status=open|triggered|acknowledged|resolved, ?team_id=.", "summary": "List incidents in the tenant, newest first. Non-admins are limited to\nincidents of teams they belong to", "tags": [ "Incident" ], "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "scope", "in": "query", "schema": { "type": "string", "default": "teams" } }, { "name": "sort", "in": "query", "schema": { "type": "string", "default": "newest" } }, { "name": "team_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `IncidentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/incidents\/{incident}": { "get": { "operationId": "incident.show", "tags": [ "Incident" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "The incident ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`IncidentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/incidents\/{incident}\/acknowledge": { "post": { "operationId": "incident.acknowledge", "summary": "Acknowledge an incident. An optional `note` is recorded on the timeline\nevent", "tags": [ "Incident" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "The incident ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "`IncidentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/incidents\/{incident}\/resolve": { "post": { "operationId": "incident.resolve", "summary": "Resolve an incident. An optional `note` is recorded on the timeline event", "tags": [ "Incident" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "The incident ID", "schema": { "type": "string" } } ], "requestBody": { "content": { "application\/json": { "schema": { "type": "object", "properties": { "note": { "type": [ "string", "null" ], "maxLength": 2000 } } } } } }, "responses": { "200": { "description": "`IncidentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/incidents\/{incident}\/comments": { "post": { "operationId": "incident.comment", "summary": "Add a free-text comment to the incident timeline. Any member who can view\nthe incident may comment", "tags": [ "Incident" ], "parameters": [ { "name": "incident", "in": "path", "required": true, "description": "The incident ID", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "body": { "type": "string", "maxLength": 2000 } }, "required": [ "body" ] } } } }, "responses": { "200": { "description": "`IncidentResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/me\/phone": { "put": { "operationId": "phone.update", "summary": "Set a candidate phone number and send a verification code by SMS. The\nnumber isn't saved on the account until verified", "tags": [ "Phone" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" } }, "required": [ "phone" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": [ "message" ] } } } }, "503": { "description": "Provider-side failure (suspended\/out-of-credit account, network):\nnothing the user can do \u2014 503, not a scary bare 502.", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "The SMS service is temporarily unavailable, so the code could not be sent. Please try again later or contact your administrator." }, "error": { "type": [ "string", "null" ] } }, "required": [ "message", "error" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/me\/phone\/verify": { "post": { "operationId": "phone.verify", "summary": "Confirm the code to mark the number verified", "tags": [ "Phone" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "code": { "type": "string", "maxLength": 10 } }, "required": [ "code" ] } } } }, "responses": { "200": { "description": "", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Phone number verified \u2014 you can now be paged by SMS." } }, "required": [ "message" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/me\/locale": { "put": { "operationId": "preferences.updateLocale", "tags": [ "Preferences" ], "requestBody": { "required": true, "content": { "application\/json": { "schema": { "type": "object", "properties": { "locale": { "type": "string", "enum": [ "en", "tr" ] } }, "required": [ "locale" ] } } } }, "responses": { "200": { "description": "`UserResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/UserResource" } }, "required": [ "data" ] } } } }, "422": { "$ref": "#\/components\/responses\/ValidationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/schedules": { "get": { "operationId": "schedule.index", "summary": "List schedules in the tenant. Non-admins are limited to schedules of\nteams they belong to. Optional ?team_id= filter", "tags": [ "Schedule" ], "parameters": [ { "name": "team_id", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ScheduleResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ScheduleResource" } }, "links": { "type": "object", "properties": { "first": { "type": [ "string", "null" ] }, "last": { "type": [ "string", "null" ] }, "prev": { "type": [ "string", "null" ] }, "next": { "type": [ "string", "null" ] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": [ "integer", "null" ], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": [ "string", "null" ], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": [ "integer", "null" ], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": [ "data", "links", "meta" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } }, "\/schedules\/{schedule}": { "get": { "operationId": "schedule.show", "tags": [ "Schedule" ], "parameters": [ { "name": "schedule", "in": "path", "required": true, "description": "The schedule ID", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ScheduleResource`", "content": { "application\/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#\/components\/schemas\/ScheduleResource" } }, "required": [ "data" ] } } } }, "403": { "$ref": "#\/components\/responses\/AuthorizationException" }, "404": { "$ref": "#\/components\/responses\/ModelNotFoundException" }, "401": { "$ref": "#\/components\/responses\/AuthenticationException" } } } } }, "components": { "securitySchemes": { "http": { "type": "http", "scheme": "bearer" } }, "schemas": { "AssignmentResource": { "type": "object", "properties": { "id": { "type": "string" }, "schedule_id": { "type": "string" }, "user_id": { "type": "string" }, "user": { "$ref": "#\/components\/schemas\/UserResource" }, "schedule": { "$ref": "#\/components\/schemas\/ScheduleResource" }, "starts_at": { "type": "string", "format": "date-time" }, "ends_at": { "type": "string", "format": "date-time" }, "notified": { "type": "boolean" } }, "required": [ "id", "schedule_id", "user_id", "starts_at", "ends_at", "notified" ], "title": "AssignmentResource" }, "DeviceTokenResource": { "type": "object", "properties": { "id": { "type": "string" }, "platform": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "token": { "type": "string" }, "active": { "type": "boolean" }, "last_used_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "platform", "name", "token", "active", "last_used_at", "created_at", "updated_at" ], "title": "DeviceTokenResource" }, "IncidentEventResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "meta": { "type": [ "array", "null" ], "items": {} }, "actor_id": { "type": [ "string", "null" ] }, "actor": { "$ref": "#\/components\/schemas\/UserResource" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "message", "meta", "actor_id", "created_at" ], "title": "IncidentEventResource" }, "IncidentResource": { "type": "object", "properties": { "id": { "type": "string" }, "team_id": { "type": "string" }, "integration_id": { "type": [ "string", "null" ] }, "parent_incident_id": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "severity": { "type": "string" }, "status": { "type": "string" }, "occurrence_count": { "type": "integer", "description": "How many times this alert has fired (1 + de-duplicated re-triggers)." }, "source": { "type": [ "string", "null" ] }, "dedup_key": { "type": [ "string", "null" ] }, "triggered_at": { "type": "string", "format": "date-time" }, "acknowledged_at": { "type": [ "string", "null" ], "format": "date-time" }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time" }, "acknowledged_by": { "type": "string", "description": "Who took each action, for a \"resolved by \u2026\" line on the detail\nscreen. Present (name or null) whenever the relation is loaded." }, "resolved_by": { "type": "string" }, "assigned_to": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "share_url": { "type": "string", "description": "The web detail page, for the app's copy-link \/ native share\nsheet. Needs a signed-in team member to open, like the app." }, "team": { "$ref": "#\/components\/schemas\/TeamResource" }, "integration": { "$ref": "#\/components\/schemas\/IntegrationResource" }, "parent": { "$ref": "#\/components\/schemas\/IncidentResource" }, "post_mortem_requirement": { "type": [ "object", "null" ], "description": "Whether this incident owes a post-mortem, who writes it, by when.\nNull for the many incidents that don't.", "properties": { "reason": { "type": [ "string", "null" ] }, "owner_id": { "type": [ "string", "null" ] }, "owner": { "type": "string" }, "due_on": { "type": "string" }, "is_overdue": { "type": "boolean" } }, "required": [ "reason", "owner_id", "due_on", "is_overdue" ] }, "children": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IncidentResource" } }, "events": { "type": "array", "items": { "$ref": "#\/components\/schemas\/IncidentEventResource" } }, "timeline": { "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "const": "delivery" }, "type": { "type": "string" }, "title": { "type": "string" }, "detail": { "type": "string" }, "detail_key": { "type": "string", "const": "delivery_to" }, "detail_vars": { "type": "object", "properties": { "name": { "type": "string" } }, "required": [ "name" ] }, "message": { "type": [ "string", "null" ] }, "meta_detail": { "type": [ "string", "null" ] }, "meta_key": { "type": [ "string", "null" ], "const": "delivery_status" }, "meta_vars": { "anyOf": [ { "type": "object", "properties": { "status": { "type": "string" } }, "required": [ "status" ] }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false } ] }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "tone": { "type": "string", "enum": [ "indigo", "info", "purple", "muted" ] } }, "required": [ "id", "kind", "type", "title", "detail", "detail_key", "detail_vars", "message", "meta_detail", "meta_key", "meta_vars", "occurred_at", "tone" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "const": "retrigger_group" }, "type": { "type": "string" }, "title": { "type": "string", "description": "Clients that predate this item kind render `title`\/`detail` like\nany other row; newer ones localise from `count` and expand\n`occurrences` to reach each re-trigger's payload." }, "detail": { "type": "string" }, "detail_key": { "type": "string", "enum": [ "event_triggered_via_source", "event_triggered_via" ] }, "detail_vars": { "anyOf": [ { "type": "object", "properties": { "integration": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "API" ] } ] }, "source": { "type": "string" } }, "required": [ "integration", "source" ] }, { "type": "object", "properties": { "integration": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "API" ] } ] } }, "required": [ "integration" ] } ] }, "message": { "type": "null" }, "meta_detail": { "type": "null" }, "meta_key": { "type": "null" }, "meta_vars": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0, "additionalItems": false }, "payload": { "type": "null" }, "actor": { "type": "null" }, "count": { "type": "string" }, "first_at": { "type": "string" }, "last_at": { "type": "string" }, "occurrences": { "type": "string" }, "occurred_at": { "type": "string" }, "tone": { "type": "string", "const": "warning" } }, "required": [ "id", "kind", "type", "title", "detail", "detail_key", "detail_vars", "message", "meta_detail", "meta_key", "meta_vars", "payload", "actor", "count", "first_at", "last_at", "occurrences", "occurred_at", "tone" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "const": "event" }, "type": { "type": "string" }, "title": { "type": "string", "enum": [ "Triggered", "Re-triggered", "Escalated", "Acknowledged", "Resolved", "Reopened", "Severity changed", "Snoozed", "Merged", "Assigned", "AI investigated", "AI suppressed paging", "Call muted by a rule", "Root cause analysis recorded", "Marked as no RCA needed", "Post-mortem published", "Comment" ] }, "detail": { "type": "string", "description": "`detail`\/`meta_detail` stay English so clients that predate the\nstructured keys keep rendering something sensible; `*_key` +\n`*_vars` let a client compose the same sentence in its own\nlanguage. Keys match the web's `incidents.*` translation keys." }, "detail_key": { "type": "string" }, "detail_vars": { "type": "string" }, "message": { "type": [ "string", "null" ] }, "meta_detail": { "type": "string" }, "meta_key": { "type": "string" }, "meta_vars": { "type": "string" }, "payload": {}, "actor": { "type": "string" }, "occurred_at": { "type": [ "string", "null" ], "format": "date-time" }, "tone": { "type": "string", "enum": [ "critical", "warning", "purple", "success", "info", "muted" ] } }, "required": [ "id", "kind", "type", "title", "detail", "detail_key", "detail_vars", "message", "meta_detail", "meta_key", "meta_vars", "payload", "actor", "occurred_at", "tone" ] } ] } }, "details": { "type": [ "array", "null" ], "description": "The raw inbound payload is only included on the detail endpoint\n(where the timeline\/events are loaded) to keep lists lean.", "items": {} }, "ai": { "type": [ "object", "null" ], "description": "The AI investigation verdict, null when AI is disabled or hasn't\nrun. Same shape as the outbound webhook's `incident.ai` block.\nDetail-only (like `details`) \u2014 the prose would bloat list pages.", "properties": { "summary": { "type": [ "string", "null" ] }, "probable_cause": { "type": [ "string", "null" ] }, "suggested_action": { "type": [ "string", "null" ] }, "recommendation": { "type": [ "string", "null" ] }, "confidence": { "type": [ "integer", "null" ] }, "analyzed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "summary", "probable_cause", "suggested_action", "recommendation", "confidence", "analyzed_at" ] }, "ai_feedback": { "type": "array", "description": "Everyone's rating of that analysis, plus the caller's own so the\napp can show its rating chips pre-selected.", "items": { "type": "object", "properties": { "id": { "type": "string" }, "rating": { "type": "string" }, "comment": { "type": [ "string", "null" ] }, "user": { "type": "string" }, "mine": { "type": "boolean", "description": "Lets the app list colleagues' verdicts without having to\nmatch on names to spot the caller's own row." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "rating", "comment", "user", "mine", "created_at" ] } }, "my_ai_feedback": { "type": [ "object", "null" ], "properties": { "rating": { "type": "string" }, "comment": { "type": [ "string", "null" ] } }, "required": [ "rating", "comment" ] } }, "required": [ "id", "team_id", "integration_id", "parent_incident_id", "title", "description", "severity", "status", "occurrence_count", "source", "dedup_key", "triggered_at", "acknowledged_at", "resolved_at", "created_at", "updated_at", "share_url", "post_mortem_requirement" ], "title": "IncidentResource" }, "IntegrationResource": { "type": "object", "properties": { "id": { "type": "string" }, "team_id": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "dedup_mode": { "type": "string" }, "is_active": { "type": "boolean" }, "last_event_at": { "type": [ "string", "null" ], "format": "date-time" }, "routing_key": { "type": "string", "description": "The routing key is the ingest secret \u2014 only managers (lead\/admin)\nmay read it, not every team member." }, "inbound_url": { "type": "string" }, "team": { "$ref": "#\/components\/schemas\/TeamResource" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "team_id", "name", "type", "dedup_mode", "is_active", "last_event_at", "created_at", "updated_at" ], "title": "IntegrationResource" }, "ParticipantResource": { "type": "object", "properties": { "id": { "type": "string" }, "position": { "type": "integer" }, "user": { "$ref": "#\/components\/schemas\/UserResource" }, "user_id": { "type": "string" } }, "required": [ "id", "position", "user_id" ], "title": "ParticipantResource" }, "RotationRuleResource": { "type": "object", "properties": { "id": { "type": "string" }, "interval_type": { "type": "string" }, "interval_days": { "type": [ "integer", "null" ] }, "shift_length_in_days": { "type": "integer" }, "shift_boundaries": { "type": [ "array", "null" ], "items": {} }, "handoff_time": { "type": "string" }, "starts_at": { "type": "string", "format": "date-time" }, "is_active": { "type": "boolean" } }, "required": [ "id", "interval_type", "interval_days", "shift_length_in_days", "shift_boundaries", "handoff_time", "starts_at", "is_active" ], "title": "RotationRuleResource" }, "ScheduleResource": { "type": "object", "properties": { "id": { "type": "string" }, "team_id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "timezone": { "type": "string" }, "is_active": { "type": "boolean" }, "team": { "$ref": "#\/components\/schemas\/TeamResource" }, "rotation_rule": { "$ref": "#\/components\/schemas\/RotationRuleResource" }, "participants": { "type": "array", "items": { "$ref": "#\/components\/schemas\/ParticipantResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "team_id", "name", "description", "timezone", "is_active", "created_at", "updated_at" ], "title": "ScheduleResource" }, "StoreDeviceTokenRequest": { "type": "object", "properties": { "token": { "type": "string", "maxLength": 512 }, "platform": { "type": "string", "enum": [ "ios", "android", "web" ] }, "name": { "type": [ "string", "null" ], "maxLength": 120 } }, "required": [ "token", "platform" ], "title": "StoreDeviceTokenRequest" }, "TeamResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "members_count": { "type": "integer" }, "schedules_count": { "type": "integer" }, "members": { "type": "array", "items": { "$ref": "#\/components\/schemas\/UserResource" } }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "slug", "description", "created_at", "updated_at" ], "title": "TeamResource" }, "UserResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string" }, "phone": { "type": [ "string", "null" ] }, "phone_verified": { "type": "boolean" }, "tenant_role": { "type": "string" }, "timezone": { "type": "string" }, "locale": { "type": "string" }, "capabilities": { "type": "object", "properties": { "manage_settings": { "type": "boolean" }, "manage_messaging": { "type": "boolean" }, "view_analytics": { "type": "boolean" }, "view_audit_log": { "type": "boolean" }, "manage_status_page": { "type": "boolean" }, "post_status_updates": { "type": "boolean" } }, "required": [ "manage_settings", "manage_messaging", "view_analytics", "view_audit_log", "manage_status_page", "post_status_updates" ] } }, "required": [ "id", "name", "email", "phone", "phone_verified", "tenant_role", "timezone", "locale", "capabilities" ], "title": "UserResource" } }, "responses": { "ValidationException": { "description": "Validation error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthenticationException": { "description": "Unauthenticated", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application\/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } } }