{
  "openapi": "3.0.3",
  "info": {
    "title": "Atlas Service Desk API",
    "version": "1.0.0",
    "description": "Atlas Service Desk (Jira-shaped). Vocabulary: Issues · Projects · Transitions · Sprints. Records are Issues, identified by issueKey (e.g. ATL-1042). Identifiers this system emits: issueKey, reporter. No authentication."
  },
  "servers": [
    {
      "url": "https://necogoode-systems.azurewebsites.net"
    }
  ],
  "tags": [
    {
      "name": "Issues"
    },
    {
      "name": "Operations"
    }
  ],
  "paths": {
    "/api/servicedesk/records": {
      "get": {
        "operationId": "listServicedeskRecords",
        "tags": [
          "Issues"
        ],
        "summary": "List Issues (newest first)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Record"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createServicedeskRecord",
        "tags": [
          "Issues"
        ],
        "summary": "Create a Issue (emits atlas.issue.created)",
        "description": "Creates a Issue in Atlas Service Desk and emits the atlas.issue.created webhook to SoloLift.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    },
                    "droppedFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "identifiers belonging to another system, dropped before the record was written"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A required field was missing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/servicedesk/records/{id}": {
      "get": {
        "operationId": "getServicedeskRecord",
        "tags": [
          "Issues"
        ],
        "summary": "Read one Issue",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "issueKey, e.g. ATL-1042",
            "example": "ATL-1042"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "patch": {
        "operationId": "updateServicedeskRecord",
        "tags": [
          "Issues"
        ],
        "summary": "Update a Issue (emits atlas.issue.updated)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "issueKey, e.g. ATL-1042",
            "example": "ATL-1042"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/servicedesk/records/{id}/transition": {
      "post": {
        "operationId": "servicedeskTransition",
        "tags": [
          "Operations"
        ],
        "summary": "Transition issue (emits atlas.issue.transitioned)",
        "description": "Move the Issue to another status in the project workflow.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "issueKey, e.g. ATL-1042",
            "example": "ATL-1042"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/servicedesk/records/{id}/events": {
      "get": {
        "operationId": "listServicedeskRecordEvents",
        "tags": [
          "Operations"
        ],
        "summary": "Every event this system has emitted for the record",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "issueKey, e.g. ATL-1042",
            "example": "ATL-1042"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/servicedesk/events": {
      "get": {
        "operationId": "listServicedeskEvents",
        "tags": [
          "Operations"
        ],
        "summary": "Every event this system has emitted (newest first)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/servicedesk/chaos": {
      "post": {
        "operationId": "servicedeskChaos",
        "tags": [
          "Operations"
        ],
        "summary": "Emit a deliberately awkward event for anomaly testing",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChaosRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/servicedesk/seed": {
      "post": {
        "operationId": "servicedeskSeedHistory",
        "tags": [
          "Operations"
        ],
        "summary": "Generate N backdated Issues with events across a date window",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeedRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/_health": {
      "get": {
        "operationId": "health",
        "tags": [
          "Operations"
        ],
        "summary": "Liveness and build stamp",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "build": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Record": {
        "type": "object",
        "properties": {
          "issueKey": {
            "type": "string",
            "description": "Issue identifier issued by Atlas Service Desk",
            "example": "ATL-1042"
          },
          "summary": {
            "type": "string",
            "description": "Summary (required on create)"
          },
          "description": {
            "type": "string",
            "description": "Description"
          },
          "project": {
            "type": "string",
            "enum": [
              "ATL",
              "OPS",
              "FAC"
            ],
            "description": "Project",
            "default": "ATL"
          },
          "issueType": {
            "type": "string",
            "enum": [
              "Service Request",
              "Task",
              "Incident",
              "Change"
            ],
            "description": "Issue type",
            "default": "Service Request"
          },
          "reporter": {
            "type": "string",
            "format": "email",
            "description": "Reporter (email) (required on create)"
          },
          "assignee": {
            "type": "string",
            "description": "Assignee",
            "default": "IT Support Centre"
          },
          "priority": {
            "type": "string",
            "enum": [
              "Low",
              "Medium",
              "High",
              "Critical"
            ],
            "description": "Priority",
            "default": "Medium"
          },
          "status": {
            "type": "string",
            "enum": [
              "Open",
              "In Progress",
              "In Review",
              "Waiting for Reporter",
              "Resolved",
              "Closed"
            ],
            "description": "Status",
            "default": "Open"
          },
          "sprint": {
            "type": "string",
            "description": "Sprint",
            "default": "IT Ops Sprint 24"
          },
          "labels": {
            "type": "string",
            "description": "Labels (comma separated)",
            "default": "onboarding,equipment"
          },
          "equipmentPackage": {
            "type": "string",
            "enum": [
              "",
              "standard",
              "specialist"
            ],
            "description": "Equipment package"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "eventCount": {
            "type": "integer",
            "description": "number of events this system has emitted for the record"
          },
          "lastDelivery": {
            "$ref": "#/components/schemas/Delivery"
          }
        }
      },
      "CreateRequest": {
        "type": "object",
        "required": [
          "summary",
          "reporter"
        ],
        "properties": {
          "summary": {
            "type": "string",
            "description": "Summary (required on create)"
          },
          "description": {
            "type": "string",
            "description": "Description"
          },
          "project": {
            "type": "string",
            "enum": [
              "ATL",
              "OPS",
              "FAC"
            ],
            "description": "Project",
            "default": "ATL"
          },
          "issueType": {
            "type": "string",
            "enum": [
              "Service Request",
              "Task",
              "Incident",
              "Change"
            ],
            "description": "Issue type",
            "default": "Service Request"
          },
          "reporter": {
            "type": "string",
            "format": "email",
            "description": "Reporter (email) (required on create)"
          },
          "assignee": {
            "type": "string",
            "description": "Assignee",
            "default": "IT Support Centre"
          },
          "priority": {
            "type": "string",
            "enum": [
              "Low",
              "Medium",
              "High",
              "Critical"
            ],
            "description": "Priority",
            "default": "Medium"
          },
          "status": {
            "type": "string",
            "enum": [
              "Open",
              "In Progress",
              "In Review",
              "Waiting for Reporter",
              "Resolved",
              "Closed"
            ],
            "description": "Status",
            "default": "Open"
          },
          "sprint": {
            "type": "string",
            "description": "Sprint",
            "default": "IT Ops Sprint 24"
          },
          "labels": {
            "type": "string",
            "description": "Labels (comma separated)",
            "default": "onboarding,equipment"
          },
          "equipmentPackage": {
            "type": "string",
            "enum": [
              "",
              "standard",
              "specialist"
            ],
            "description": "Equipment package"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the record and the emitted event (used for seeding history)."
          },
          "emit": {
            "type": "boolean",
            "default": true,
            "description": "Optional. false suppresses the webhook to SoloLift."
          }
        }
      },
      "UpdateRequest": {
        "type": "object",
        "properties": {
          "summary": {
            "type": "string",
            "description": "Summary (required on create)"
          },
          "description": {
            "type": "string",
            "description": "Description"
          },
          "project": {
            "type": "string",
            "enum": [
              "ATL",
              "OPS",
              "FAC"
            ],
            "description": "Project",
            "default": "ATL"
          },
          "issueType": {
            "type": "string",
            "enum": [
              "Service Request",
              "Task",
              "Incident",
              "Change"
            ],
            "description": "Issue type",
            "default": "Service Request"
          },
          "reporter": {
            "type": "string",
            "format": "email",
            "description": "Reporter (email) (required on create)"
          },
          "assignee": {
            "type": "string",
            "description": "Assignee",
            "default": "IT Support Centre"
          },
          "priority": {
            "type": "string",
            "enum": [
              "Low",
              "Medium",
              "High",
              "Critical"
            ],
            "description": "Priority",
            "default": "Medium"
          },
          "status": {
            "type": "string",
            "enum": [
              "Open",
              "In Progress",
              "In Review",
              "Waiting for Reporter",
              "Resolved",
              "Closed"
            ],
            "description": "Status",
            "default": "Open"
          },
          "sprint": {
            "type": "string",
            "description": "Sprint",
            "default": "IT Ops Sprint 24"
          },
          "labels": {
            "type": "string",
            "description": "Labels (comma separated)",
            "default": "onboarding,equipment"
          },
          "equipmentPackage": {
            "type": "string",
            "enum": [
              "",
              "standard",
              "specialist"
            ],
            "description": "Equipment package"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the record and the emitted event (used for seeding history)."
          },
          "emit": {
            "type": "boolean",
            "default": true,
            "description": "Optional. false suppresses the webhook to SoloLift."
          }
        }
      },
      "ActionRequest": {
        "type": "object",
        "required": [
          "to"
        ],
        "properties": {
          "to": {
            "type": "string",
            "enum": [
              "Open",
              "In Progress",
              "In Review",
              "Waiting for Reporter",
              "Resolved",
              "Closed"
            ],
            "default": "In Review"
          },
          "comment": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the emitted event."
          }
        }
      },
      "ChaosRequest": {
        "type": "object",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "out_of_order",
              "duplicate",
              "omit_field",
              "unknown_type"
            ]
          },
          "recordId": {
            "type": "string",
            "description": "defaults to the most recent record"
          }
        }
      },
      "SeedRequest": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "default": 5,
            "maximum": 200
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "start of the backdating window"
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "end of the backdating window"
          },
          "includeAction": {
            "type": "boolean",
            "default": true,
            "description": "also emit atlas.issue.transitioned per record"
          },
          "specialistRatio": {
            "type": "number",
            "default": 0.15
          },
          "fieldRatios": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "probability a normally-optional field is populated, e.g. {\"CostCentre\":0.35}"
          },
          "template": {
            "type": "object",
            "description": "field values forced on every seeded record"
          },
          "emit": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "Delivery": {
        "type": "object",
        "description": "the outcome of the SoloLift webhook for the latest event",
        "properties": {
          "httpStatus": {
            "type": "integer"
          },
          "receiptStatus": {
            "type": "string"
          },
          "receiptReason": {
            "type": "string"
          },
          "externalEventId": {
            "type": "string"
          },
          "transportError": {
            "type": "string",
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "system": {
            "type": "string",
            "enum": [
              "servicedesk"
            ]
          },
          "recordId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "enum": [
              "atlas.issue.created",
              "atlas.issue.updated",
              "atlas.issue.transitioned",
              "atlas.issue.frobnicated"
            ]
          },
          "externalEventId": {
            "type": "string"
          },
          "eventSourceId": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "emittedAt": {
            "type": "string",
            "format": "date-time"
          },
          "chaos": {
            "type": "string",
            "nullable": true,
            "enum": [
              "out_of_order",
              "duplicate",
              "omit_field",
              "unknown_type",
              null
            ]
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "delivery": {
            "$ref": "#/components/schemas/Delivery"
          }
        }
      }
    }
  }
}