{ "openapi": "3.0.0", "info": { "title": "FSCharter API", "version": "1", "description": "The supported public API for building tools against FSCharter.\n\nCreate a token at Profile → API Access, or use the OAuth flow so players can sign in to your app without giving it a password.\n\nTwo things worth reading before you start. A scope lets a tool ASK for something; the player's company role still decides what it gets, and a 403 names the privilege that was missing. And anything that costs money is two calls: POST /api/v1/quotes for a price, then send that quote with the purchase, so your users see the cost before they commit to it.", "contact": { "name": "FSCharter Support", "url": "https://v2.fscharter.net/help" } }, "servers": [ { "url": "https://v2.fscharter.net", "description": "FSCharter" } ], "paths": { "/api/v1/agreement-variants": { "get": { "tags": [ "Public API v1" ], "description": "Every kind of agreement that exists, with what an airport must be for each. Shared reference data, so no company and no privilege.\n\n**Requires:** scope `read:agreements`, plus the company privilege `view-agreements`.", "operationId": "fb27e37b8747cca990714546d1ba9f08", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AgreementVariantResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:agreements" } }, "security": [ { "bearerAuth": [ "read:agreements" ] } ] } }, "/api/v1/agreements/{agreement}": { "get": { "tags": [ "Public API v1" ], "description": "One slot agreement. Same shape as a row in the company list, so a client writes one parser.\n\n**Requires:** scope `read:agreements`, plus the company privilege `view-agreements`.", "operationId": "8851cb615df5ff036263f70ca7811a0f", "parameters": [ { "name": "agreement", "in": "path", "description": "Agreement uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AgreementResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:agreements, or the role lacks view-agreements" }, "404": { "description": "No such agreement, or the token holder is not a member of the company holding it" } }, "security": [ { "bearerAuth": [ "read:agreements" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Give up a slot agreement. Not reversible: the slot returns to the pool and someone else may sign it. Refused when the variant is not cancellable or the minimum term has not run — both are reported on every agreement so a client need not offer a button that cannot work.\n\n**Requires:** scope `write:agreements`, plus the company privileges `view-agreements`, `cancel-agreements`.", "operationId": "189785f8d3fec9085bee00cdc49bc7c3", "parameters": [ { "name": "agreement", "in": "path", "description": "Agreement UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AgreementCancellation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:agreements, or the role lacks cancel-agreements" }, "404": { "description": "No such agreement, or the token holder is not a member of its company" }, "422": { "description": "Not cancellable, or the minimum term has not run" } }, "security": [ { "bearerAuth": [ "write:agreements" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Rename a slot agreement, or change who may use it. Every field is optional and an omitted one is left alone, which matters for `access`: treating it as absent-means-none would evict a partner's aircraft on a rename.\n\n**Requires:** scope `write:agreements`, plus the company privileges `view-agreements`, `sign-agreements`.", "operationId": "da761e8f926b80618d06ab26d2c0f25a", "parameters": [ { "name": "agreement", "in": "path", "description": "Agreement uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true }, "access": { "description": "Capability sharing, in the game's own shape.", "type": "array", "items": { "type": "object" }, "nullable": true }, "configuration": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AgreementResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:agreements, or the role lacks sign-agreements" }, "404": { "description": "No such agreement, or the token holder is not a member of the company holding it" }, "422": { "description": "Refused: an access configuration the agreement cannot support" } }, "security": [ { "bearerAuth": [ "write:agreements" ] } ] } }, "/api/v1/aircraft": { "get": { "tags": [ "Public API v1" ], "description": "Every aircraft you can see, across all your companies. Companies where your role lacks view-aircraft are absent rather than refused, so this stays useful to someone who holds it at four companies out of six.\n\n**Requires:** scope `read:fleet`, plus the company privilege `view-aircraft`.", "operationId": "9ec684ec19959cac72d290325f96eb7a", "parameters": [ { "name": "airport", "in": "query", "description": "Only aircraft standing at this ICAO.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft-categories": { "get": { "tags": [ "Public API v1" ], "description": "The seven aircraft categories. `code` is what the hours breakdown on GET /me and GET /pilots/{username}/statistics is keyed by, so this is how you turn SRA into words.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "8227bdb11a9bbc32813211eea8848b1c", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftCategoryResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/aircraft-service-types": { "get": { "tags": [ "Public API v1" ], "description": "Kinds of maintenance and shop work: the A/B/C/D check ladder plus tail-number changes and seat reconfigurations. `slug` is what the maintenance endpoints name.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "2ae5144885fa3a72bb9e1a68e3eab1b9", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftServiceTypeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/aircraft-types": { "get": { "tags": [ "Public API v1" ], "description": "Every aircraft the game has. The catalogue behind buying an aircraft, mapping a SimBrief airframe and building an aircraft group. `?search=` matches ICAO code, manufacturer and model.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "1df45481c047b3612e97879e5d8ece7f", "parameters": [ { "name": "search", "in": "query", "description": "Matches ICAO code, manufacturer and model.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftTypeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/aircraft-types/{aircraftType}": { "get": { "tags": [ "Public API v1" ], "description": "One aircraft type in full, addressed by slug. The ICAO code is not unique across variants of the same airframe, which is why the slug is the key.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "8b0208d88b1a653604c61ad858d178ad", "parameters": [ { "name": "aircraftType", "in": "path", "description": "Aircraft type slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftTypeResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" }, "404": { "description": "No aircraft type with that slug" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/aircraft-types/{aircraftType}/validate-tail-number": { "get": { "tags": [ "Public API v1" ], "description": "Is this registration legal for this airframe in this country, and still free? Check before buying, so you can tell somebody their chosen tail number is taken before charging them for a plane. `valid: false` with a message is a normal 200.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "172c9e935f22e0e1270ca7c056c263d0", "parameters": [ { "name": "aircraftType", "in": "path", "description": "Aircraft type slug", "required": true, "schema": { "type": "string" } }, { "name": "tail_number", "in": "query", "description": "The registration to check.", "required": true, "schema": { "type": "string", "example": "G-ABCD" } }, { "name": "country", "in": "query", "description": "ISO alpha-2 country of registration, e.g. GB.", "required": true, "schema": { "type": "string", "example": "GB" } } ], "responses": { "200": { "description": "Answered — check `valid`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1TailNumberValidation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" }, "404": { "description": "No such aircraft type or country" }, "422": { "description": "Missing parameters, or that country registers no aircraft of this kind" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/aircraft/{aircraft}": { "get": { "tags": [ "Public API v1" ], "description": "One aircraft by tail number. Same shape as a row in the fleet list.\n\n**Requires:** scope `read:fleet`, plus the company privilege `view-aircraft`.", "operationId": "dcc74d742d41ce06a29d5fe145e65063", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number, e.g. G-ABCD", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/available-ranks": { "get": { "tags": [ "Public API v1" ], "description": "Which of the owning company's ranks may fly this aircraft, and where YOU stand against each. `can_fly_aircraft` is about the rank; `eligible` is about you. Both must be true.\n\n**Requires:** scope `read:fleet`, plus the company privilege `view-aircraft`.", "operationId": "eac10baaedaef2d7781114b275914795", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftRankResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/enter-slot": { "post": { "tags": [ "Public API v1" ], "description": "Put the aircraft into a container: a parking slot, a hangar, a stand, a service centre for a C or D check, a tail-number shop, or a seat reconfiguration bay. One endpoint because it is one mechanic in the game — the container decides what happens. Name the slot with a usage_uuid from the capacity block of /agreements or /buildings. The privilege required is the container's (manually-hangar, perform-d-checks, change-aircraft-tail-numbers and so on).\n\n**Requires:** scope `write:fleet`, plus the company privilege `view-aircraft`, plus any one of `manually-move-aircraft-to-slot`, `manually-hangar-aircraft`, `manually-stand-aircraft`, `perform-c-checks`, `perform-d-checks`, `change-aircraft-tail-numbers`, `reconfigure-seats`.", "operationId": "b37ed4ed483845a54ef8b23040966871", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "usage_uuid" ], "properties": { "usage_uuid": { "description": "From the `capacity` block of GET /companies/{icao}/agreements or /buildings. Pick one with free > 0.", "type": "string" }, "configuration": { "description": "Container-specific. change-tail-number wants {\"newTailNumber\": \"G-NEW\"}; reconfigure-seats wants {\"first\": 8, \"business\": 20, \"economy\": 100}. Ignored by containers that just hold aircraft.", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success — returns the aircraft", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks the container's privilege" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "Refused: no capacity, aircraft on a job, wrong airport, or an invalid configuration for this container" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/ferry-estimate": { "get": { "tags": [ "Public API v1" ], "description": "What ferrying this aircraft to another airport empty would cost. An ESTIMATE, not a quote: nothing is locked, and fuel and fees move with the economy.\n\n**Requires:** scope `read:fleet`, plus the company privileges `view-aircraft`, `create-ferry-jobs`.", "operationId": "1935dde0c997cbc08aae77797936641d", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } }, { "name": "to", "in": "query", "description": "Destination ICAO.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1FerryEstimate" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks create-ferry-jobs" }, "404": { "description": "No such aircraft" }, "422": { "description": "`to` missing, or no airport with that ICAO" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/ferry-jobs": { "post": { "tags": [ "Public API v1" ], "description": "Fly the aircraft to another airport empty, to reposition it. Costs fuel, ATC and landing fees; see /ferry-estimate first. The job is created already accepted.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `create-ferry-jobs`.", "operationId": "af602596460a6ae0f4155c9fddf682e7", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "to" ], "properties": { "to": { "description": "Destination ICAO.", "type": "string", "example": "EGLL" } }, "type": "object" } } } }, "responses": { "200": { "description": "Ferry job created and accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks create-ferry-jobs" }, "404": { "description": "No such aircraft, or no airport with that ICAO" }, "422": { "description": "Refused: aircraft already on a job, airborne, in service, or cannot reach the destination" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/hireability": { "patch": { "tags": [ "Public API v1" ], "description": "Offer one of your aircraft for hire, or withdraw it. The company segment the internal API carries is dropped here: a tail number already identifies exactly one company.\n\n**Requires:** scope `write:market`, plus the company privilege `configure-aircraft-hiring`.", "operationId": "c883ac504d8ed93f5d73c86b70aa2645", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "allow_hire" ], "properties": { "allow_hire": { "type": "boolean", "example": true }, "filters": { "description": "Who may hire it. Passed through as the game's own structure, which is still growing.", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Hireability" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market, or the role lacks configure-aircraft-hiring" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "`allow_hire` is required. It is never defaulted: silently withdrawing an aircraft because a field was omitted would leave the owner wondering why the hires stopped." } }, "security": [ { "bearerAuth": [ "write:market" ] } ] } }, "/api/v1/aircraft/{aircraft}/image": { "put": { "tags": [ "Public API v1" ], "description": "Set the aircraft's photo. The only v1 endpoint taking multipart/form-data rather than JSON, because it takes a file. JPEG or PNG, 3 MB maximum.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `change-aircraft-settings`.", "operationId": "a569473c906061a74fe799311b0f73ae", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "required": [ "image" ], "properties": { "image": { "type": "string", "format": "binary" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftImage" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks change-aircraft-settings" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "Not an image, too large, or an unsupported format" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Remove the aircraft's photo, returning it to the default for its type.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `change-aircraft-settings`.", "operationId": "764ad428a242c644d5d3420b35cbd364", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftImage" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks change-aircraft-settings" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/logbook": { "get": { "tags": [ "Public API v1" ], "description": "Every flight this aircraft has made, newest first. Check `valid` before paying anything against a flight: it is false when the game rejected the flight as implausible.\n\n**Requires:** scope `read:fleet`, plus the company privileges `view-aircraft`, `view-aircraft-logbooks`.", "operationId": "d1c98da32ff496daa670b9492ca6a1f2", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "`landed` for finished flights only.", "required": false, "schema": { "type": "string", "enum": [ "enroute", "landed" ] } }, { "name": "departure", "in": "query", "description": "Departure ICAO.", "required": false, "schema": { "type": "string" } }, { "name": "arrival", "in": "query", "description": "Arrival ICAO.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1FlightResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft-logbooks" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/registration-airport": { "get": { "tags": [ "Public API v1" ], "description": "Where the aircraft is REGISTERED, which is not where it currently is. The registration airport decides the tail number country and where parking and crew costs fall.\n\n**Requires:** scope `read:fleet`, plus the company privilege `view-aircraft`.", "operationId": "dfcfb0b988362b6dbe7b7d5ee97407f3", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AirportResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft" }, "404": { "description": "No such aircraft, or it has no registration airport" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/seats": { "post": { "tags": [ "Public API v1" ], "description": "Change the cabin layout using one of the aircraft's free reconfigurations. Once those are used up this is refused, and reconfiguring becomes a slot service via /enter-slot.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `reconfigure-seats`.", "operationId": "f0b9a3fb4f95726471c4996e98833fd6", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "first_seats", "business_seats", "economy_seats" ], "properties": { "first_seats": { "type": "integer", "example": 8 }, "business_seats": { "type": "integer", "example": 20 }, "economy_seats": { "type": "integer", "example": 100 } }, "type": "object" } } } }, "responses": { "200": { "description": "Success — returns the aircraft", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks reconfigure-seats" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "Refused: no free reconfigurations left, layout does not fit the airframe, or the aircraft is busy" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/sell": { "post": { "tags": [ "Public API v1" ], "description": "Sell an aircraft. Send a `price` to list it in the classifieds, which is reversible with DELETE on this path. Omit `price` and the broker buys it immediately at its calculated value, which is not reversible.\n\n**Requires:** scope `write:market`, plus the company privilege `sell-aircraft`.", "operationId": "246d0ab88fe05d8791f3166edde113fb", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "price": { "description": "Asking price in pence. Omit entirely to sell to the broker instead.", "type": "integer", "example": 4250000, "nullable": true }, "description": { "description": "Free text shown on the listing.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Sold or listed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftSale" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market, or the role lacks sell-aircraft" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "Refused: aircraft on a job, in service, frozen, or already listed" } }, "security": [ { "bearerAuth": [ "write:market" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Take a classified listing back off the market. Only reaches listings; a broker sale has already happened and cannot be undone.\n\n**Requires:** scope `write:market`, plus the company privilege `sell-aircraft`.", "operationId": "f59a25f9b158441bb1c2443af47fb12d", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawn", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1SaleWithdrawn" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market, or the role lacks sell-aircraft" }, "404": { "description": "No such aircraft, or it has no active listing" } }, "security": [ { "bearerAuth": [ "write:market" ] } ] } }, "/api/v1/aircraft/{aircraft}/service": { "post": { "tags": [ "Public API v1" ], "description": "Book a maintenance check. A and B checks are free anywhere the aircraft is parked. C and D checks on a general aviation aircraft are done in the field for a fee; on an airliner they need a service centre, which means /enter-slot instead. The privilege required is the check's own (perform-a-checks and so on), read from the service type rather than fixed here.\n\n**Requires:** scope `write:fleet`, plus the company privilege `view-aircraft`, plus any one of `perform-a-checks`, `perform-b-checks`, `perform-c-checks`, `perform-d-checks`.", "operationId": "ffeae731afe66ede2062d0843653e311", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "check" ], "properties": { "check": { "description": "Slug from GET /aircraft/{registration}/service-schedule.", "type": "string", "example": "a-check" } }, "type": "object" } } } }, "responses": { "200": { "description": "Booked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ServiceBooking" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks the check's privilege" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "Refused: airborne, on a job, already in service, not yet due, an airliner needing a service centre, or not a maintenance check" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/service-automation": { "patch": { "tags": [ "Public API v1" ], "description": "Turn a maintenance check's automation on or off. With it on, the game books the check as it falls due; with it off, an overdue check will ground the aircraft. Note this is a DIFFERENT path from POST /service, which performs a check now.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `change-aircraft-service-automation`.", "operationId": "d7a2f1efec3035cf878b80bc53365684", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "check", "automatic" ], "properties": { "check": { "description": "Service type slug from /service-schedule.", "type": "string", "example": "a-check" }, "automatic": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ServiceAutomation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks change-aircraft-service-automation" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/service-records": { "get": { "tags": [ "Public API v1" ], "description": "Maintenance already carried out, newest first. A null `complete_at` means the check is still running and the aircraft cannot take a job.\n\n**Requires:** scope `read:fleet`, plus the company privileges `view-aircraft`, `view-aircraft-service-records`.", "operationId": "a48cc264cb16e76314d27988cab502b8", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } }, { "name": "check", "in": "query", "description": "Service type slug, e.g. a-check.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ServiceRecordResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft-service-records" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/service-schedule": { "get": { "tags": [ "Public API v1" ], "description": "When each maintenance check is next due, most urgent first.\n\n**Requires:** scope `read:fleet`, plus the company privileges `view-aircraft`, `view-aircraft-service-records`.", "operationId": "1f2e64764647a143898469e6e7c1e423", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number, e.g. G-ABCD", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftServiceScheduleResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft-service-records" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/transfer": { "post": { "tags": [ "Public API v1" ], "description": "Hand an aircraft to another company. The caller must be staff of BOTH, and the receiver must accept asset transfers. Every rule the website applies applies here, including the net-worth floor.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `transfer-aircraft`.", "operationId": "16bb5ea82ddaf07ddb848475f2e57561", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "to" ], "properties": { "to": { "description": "Receiving company ICAO.", "type": "string", "example": "BSC" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success — returns the aircraft under its new owner", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks transfer-aircraft" }, "404": { "description": "No such aircraft, or the caller is not staff of both companies" }, "422": { "description": "Refused: active job, frozen, receiver declines transfers, receiver AOC too low, or the sender's net worth would go negative" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/transfer-preview": { "get": { "tags": [ "Public API v1" ], "description": "What transferring this aircraft would do to the sender's net worth. Read it before POST /transfer, which refuses if net worth would go negative. `would_be_refused` states the outcome outright.\n\n**Requires:** scope `read:fleet`, plus the company privileges `view-aircraft`, `transfer-aircraft`.", "operationId": "c8e4e279a41da8f39180acc3c06385c9", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1TransferPreview" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks transfer-aircraft" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] } }, "/api/v1/aircraft/{aircraft}/vacate-slot": { "post": { "tags": [ "Public API v1" ], "description": "Take the aircraft out of whatever it is in, and re-park it if there is somewhere to go. Takes no body: an aircraft is in at most one container, so there is nothing to name. Services in progress cannot be abandoned and are refused.\n\n**Requires:** scope `write:fleet`, plus the company privileges `view-aircraft`, `manually-remove-aircraft-from-slot`.", "operationId": "47c9a00204fc12322ad5f73549fa00f2", "parameters": [ { "name": "aircraft", "in": "path", "description": "Tail number", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns the aircraft", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:fleet, or the role lacks manually-remove-aircraft-from-slot" }, "404": { "description": "No such aircraft, or the token holder is not a member of its company" }, "422": { "description": "The aircraft is not in a slot, or is undergoing a service that cannot be cancelled" } }, "security": [ { "bearerAuth": [ "write:fleet" ] } ] } }, "/api/v1/airports/{airport}": { "get": { "tags": [ "Public API v1" ], "description": "One airport: size, runways by surface, elevation and position. Shared reference data — the same answer for every token, and nothing about who operates there.\n\n**Requires:** scope `read:airports` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "c7de68ffbbf0d64a4a4f3495b5e1b2c7", "parameters": [ { "name": "airport", "in": "path", "description": "Airport ICAO, e.g. EGLL", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AirportResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:airports" }, "404": { "description": "No such airport" } }, "security": [ { "bearerAuth": [ "read:airports" ] } ] } }, "/api/v1/building-variants": { "get": { "tags": [ "Public API v1" ], "description": "The catalogue of buildings that can be bought, with what each one requires. Reference data: the same for everyone. Read it before POST /companies/{icao}/buildings, which names a variant by slug.\n\n**Requires:** scope `read:base` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "377e58238b6579bac9f9e4b0a86d2551", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BuildingVariantResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:base" } }, "security": [ { "bearerAuth": [ "read:base" ] } ] } }, "/api/v1/buildings/{building}": { "get": { "tags": [ "Public API v1" ], "description": "One building. Same shape as a row in the company list.\n\n**Requires:** scope `read:base`, plus the company privilege `view-buildings`.", "operationId": "0faf26dd12b153e5b6998b99cf7959fe", "parameters": [ { "name": "building", "in": "path", "description": "Building uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1BuildingResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:base, or the role lacks view-buildings" }, "404": { "description": "No such building, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:base" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Sell a building back. QUOTED, which is unusual for a DELETE: the refund is a percentage that decays with age, so the figure is priced when you ask and locked briefly. Send the quote uuid as `quote`.\n\n**Requires:** scope `write:base`, plus the company privilege `sell-buildings`.", "operationId": "4abe064167e86b57b08049d375efe596", "parameters": [ { "name": "building", "in": "path", "description": "Building uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote" ], "properties": { "quote": { "description": "Quote uuid from POST /api/v1/quotes with `for: building-sale`.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Sold", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1EstateSale" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks sell-buildings" }, "404": { "description": "No such building, or the token holder is not a member of its company" }, "422": { "description": "Refused: quote missing or spent, or aircraft are still using capabilities this building provides" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Rename a building, or change who may use it. Not an upgrade: a building's variant is fixed once bought, and a bigger hangar is a separate purchase. Only operations centres upgrade in place.\n\n**Requires:** scope `write:base`, plus the company privilege `purchase-buildings`.", "operationId": "58589370ad7c8508f51cae482ea07572", "parameters": [ { "name": "building", "in": "path", "description": "Building uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "access": { "type": "array", "items": { "type": "object" }, "nullable": true }, "configuration": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1BuildingResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks purchase-buildings" }, "404": { "description": "No such building, or the token holder is not a member of its company" }, "422": { "description": "Refused: an access configuration the building cannot support" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] } }, "/api/v1/capability-types": { "get": { "tags": [ "Public API v1" ], "description": "What a building or slot agreement can do, as a catalogue. For a company's actual capacity at an airport, use GET /companies/{icao}/capabilities/{slug}.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "2615a7dffe8d56194c46bda7549118ef", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CapabilityTypeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/classifieds": { "get": { "tags": [ "Public API v1" ], "description": "Used aircraft other players have listed for sale. The same list for everyone, so no company and no privilege. Supports ?search=.\n\n**Requires:** scope `read:market` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "00d0fa03102008354fb60082cea16297", "parameters": [ { "name": "search", "in": "query", "description": "Free-text search over listings.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ClassifiedListingResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:market" } }, "security": [ { "bearerAuth": [ "read:market" ] } ] } }, "/api/v1/classifieds/{listing}": { "get": { "tags": [ "Public API v1" ], "description": "One listing, same shape as a row in the list. Answers 404 once it is sold or withdrawn, so a client re-checking before buying gets a clear answer.\n\n**Requires:** scope `read:market` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "0968d73e76ab1bdb34383a6379202172", "parameters": [ { "name": "listing", "in": "path", "description": "Listing uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1ClassifiedListingResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:market" }, "404": { "description": "No such listing, or it is no longer for sale" } }, "security": [ { "bearerAuth": [ "read:market" ] } ] } }, "/api/v1/classifieds/{listing}/purchase": { "post": { "tags": [ "Public API v1" ], "description": "Buy a used aircraft from another player at the seller's asking price. No quote: the price is fixed by the seller and visible on the listing.\n\n**Requires:** scope `write:market`, plus the company privilege `purchase-aircraft`.", "operationId": "186b9cb6036e8600d9a9b1d8a203c133", "parameters": [ { "name": "listing", "in": "path", "description": "Listing uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "company" ], "properties": { "company": { "description": "ICAO of YOUR company doing the buying.", "type": "string", "example": "BLW" } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchased — returns the aircraft under its new owner", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market, or the role lacks purchase-aircraft" }, "404": { "description": "No such listing or company" }, "422": { "description": "Refused: already sold, cannot afford it, or AOC level too low for the type" } }, "security": [ { "bearerAuth": [ "write:market" ] } ] } }, "/api/v1/commodities": { "get": { "tags": [ "Public API v1" ], "description": "Everything the game flies for money: passengers by class, cargo and freight. The demand-engine and pricing internals on these rows are deliberately not published.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "da51b10c0b309971a40cf24ca18ecb14", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CommodityResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/companies": { "get": { "tags": [ "Public API v1" ], "description": "The companies the token holder is staff of. The entry point for any tool: everything else in v1 is addressed by company ICAO.\n\n**Requires:** scope `read:company` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "333c101cc9f34f524f381fb309853729", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry read:company" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] } }, "/api/v1/companies/{company}": { "get": { "tags": [ "Public API v1" ], "description": "One company the token holder is staff of.\n\n**Requires:** scope `read:company`, plus membership of the company.", "operationId": "817f7dfcd771ed8dbd2229372618c1a4", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry read:company" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Rename or update the company's settings. accepts_asset_transfers and owner_salary_percentage are not accepted here — they carry their own privileges the internal API gates separately. Changing `icao` changes the URL every other v1 endpoint for this company uses.\n\n**Requires:** scope `write:operations`, plus the company privilege `update-company`.", "operationId": "0ac2177d0ac321965cf079bdfead146f", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "icao": { "type": "string" }, "description": { "type": "string", "nullable": true }, "simbrief_airline_code": { "type": "string", "nullable": true }, "allow_economy_to_business_upgrades": { "type": "boolean" }, "allow_economy_to_first_upgrades": { "type": "boolean" }, "allow_business_cabin_upgrades": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks update-company" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "The name or ICAO is taken, or a field is invalid" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/companies/{company}/activity": { "get": { "tags": [ "Public API v1" ], "description": "The company's activity log. No privilege required beyond membership — this is a log of what members did, not financial detail.\n\n**Requires:** scope `read:operations`, plus membership of the company.", "operationId": "abbe36633f3ab4da80bc08cfea5d2732", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyActivityResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:operations" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:operations" ] } ] } }, "/api/v1/companies/{company}/agreements": { "get": { "tags": [ "Public API v1" ], "description": "The airport slot agreements this company holds, with how much of each one is in use.\n\n**Requires:** scope `read:agreements`, plus the company privilege `view-agreements`.", "operationId": "2dc7f944141fcb4493ee9b754f582063", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "owned", "in": "query", "description": "Only agreements this company owns. Off by default, because a partner's slot is one you can actually park in and /enter-slot will accept it.", "required": false, "schema": { "type": "boolean" } }, { "name": "airport", "in": "query", "description": "Narrow to one airport by ICAO.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AgreementResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:agreements, or the role lacks view-agreements" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:agreements" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Sign a slot agreement at an airport. Commits the company to a recurring cost and often a minimum term — check the variant's `requires` block against GET /airports/{icao} first, so a refusal can be explained before it happens.\n\n**Requires:** scope `write:agreements`, plus the company privileges `view-agreements`, `sign-agreements`.", "operationId": "1e17123074f3ee7163f01b3dbb243977", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "airport", "variant" ], "properties": { "airport": { "description": "Airport ICAO.", "type": "string", "example": "EGLL" }, "variant": { "description": "Variant SLUG from GET /agreement-variants. Slugs are stable; names are not.", "type": "string", "example": "large-domestic-slot" }, "name": { "description": "Optional label for your own reference.", "type": "string", "example": "LHR Stand 12" } }, "type": "object" } } } }, "responses": { "200": { "description": "Signed — returns the agreement with its capacity", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AgreementResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:agreements, or the role lacks sign-agreements" }, "404": { "description": "No such company, or the token holder is not a member" }, "422": { "description": "Refused: airport too small or too large for the variant, no operations centre of the required size in that country, or unaffordable" } }, "security": [ { "bearerAuth": [ "write:agreements" ] } ] } }, "/api/v1/companies/{company}/aircraft": { "get": { "tags": [ "Public API v1" ], "description": "A company's fleet.\n\n**Requires:** scope `read:fleet`, plus the company privilege `view-aircraft`.", "operationId": "64b54bbe346950c7e27dbd9aac93b0d1", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:fleet, or the role lacks view-aircraft" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:fleet" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Buy a new aircraft from the manufacturer. Quote it first with POST /quotes using `for: aircraft`, then send the quote uuid here. The AOC level check against the type's maximum takeoff weight applies exactly as it does on the website.\n\n**Requires:** scope `write:market`, plus the company privilege `purchase-aircraft`.", "operationId": "630c0bd4f209f671e6ed4a92ca6733d6", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "type", "registration_airport", "first_seats", "business_seats", "economy_seats" ], "properties": { "quote": { "description": "Quote uuid from POST /api/v1/quotes.", "type": "string" }, "type": { "description": "Aircraft type slug.", "type": "string", "example": "cessna-172" }, "registration_airport": { "description": "ICAO where the aircraft will be registered. Decides its tail number country and where standing costs fall.", "type": "string", "example": "EGCC" }, "first_seats": { "type": "integer", "example": 0 }, "business_seats": { "type": "integer", "example": 0 }, "economy_seats": { "type": "integer", "example": 4 }, "tail_number": { "description": "Optional. One is generated for the registration country when omitted.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Purchased", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1AircraftResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market, or the role lacks purchase-aircraft" }, "404": { "description": "No such company, type or airport" }, "422": { "description": "Refused: quote missing or spent, AOC level too low for the type, cannot afford it, or an invalid seat layout" } }, "security": [ { "bearerAuth": [ "write:market" ] } ] } }, "/api/v1/companies/{company}/aoc": { "post": { "tags": [ "Public API v1" ], "description": "Buy a higher Air Operator Certificate. The AOC level caps what the company may fly by aircraft maximum takeoff weight, and is checked when buying an aircraft and when receiving one by transfer, so a puzzling refusal on either is often an AOC problem rather than a money one. Upwards only, and charged: quote it first with `for: aoc`.\n\n**Requires:** scope `write:finance`, plus the company privilege `view-finances`.", "operationId": "061d9bd33c0020896dcdc19e5df22d4a", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "level" ], "properties": { "quote": { "type": "string" }, "level": { "type": "string", "enum": [ "small", "medium", "large" ], "example": "medium" } }, "type": "object" } } } }, "responses": { "200": { "description": "Upgraded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AocLevel" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:finance, or the role lacks view-finances" }, "404": { "description": "No such company" }, "422": { "description": "Refused: quote missing or spent, the level is not an upgrade, or the company cannot afford it" } }, "security": [ { "bearerAuth": [ "write:finance" ] } ] } }, "/api/v1/companies/{company}/buildings": { "get": { "tags": [ "Public API v1" ], "description": "The buildings this company owns, with how much of each one is in use. Same capacity shape as an agreement.\n\n**Requires:** scope `read:base`, plus the company privilege `view-buildings`.", "operationId": "203e84e880d9d81e07f376837189bec7", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "owned", "in": "query", "description": "Only buildings this company owns. Off by default, because a partner's slot is one you can actually park in and /enter-slot will accept it.", "required": false, "schema": { "type": "boolean" } }, { "name": "airport", "in": "query", "description": "Narrow to one airport by ICAO.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1BuildingResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:base, or the role lacks view-buildings" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:base" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Buy a building at an airport. Quote it first with POST /quotes using `for: building`. What each variant requires is in GET /building-variants, so a client can check before sending a request that will be refused.\n\n**Requires:** scope `write:base`, plus the company privilege `purchase-buildings`.", "operationId": "c19c103982b936e1c73618f3d411ebe1", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "airport", "variant" ], "properties": { "quote": { "description": "Quote uuid from POST /api/v1/quotes.", "type": "string" }, "airport": { "type": "string", "example": "EGCC" }, "variant": { "description": "Building variant slug.", "type": "string", "example": "large-hangar" }, "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "access": { "description": "Who else may use it, in the game's own shape.", "type": "array", "items": { "type": "object" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Bought", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1BuildingResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks purchase-buildings" }, "404": { "description": "No such company" }, "422": { "description": "Refused: quote missing or spent, cannot afford it, or the airport lacks the operations centre this variant requires" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] } }, "/api/v1/companies/{company}/current-month-profit": { "get": { "tags": [ "Public API v1" ], "description": "Income, expenses and the difference for this calendar month, in pence. Income counts job and fuel receipts; expenses count every outgoing payment. Not the same as the balance, which carries over.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "4d9d9cd30ceaad2b2fe899fb40a548ea", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CurrentMonthProfit" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/demand/release": { "post": { "tags": [ "Public API v1" ], "description": "Hand collaborative demand to the pool for other companies to fly. ONE endpoint replacing eleven internal paths that differ only in which demand they select: name `uuids`, or narrow with `urgent`, `at` and `going_to`, or send nothing to release everything releasable. What counts as releasable (collaborative, yours, still available) and what counts as urgent are the game's definitions, shared with the website.\n\n**Requires:** scope `write:demand`, plus the company privilege `release-collaborative-demand`.", "operationId": "30035ae38b5e50ea72a600d03c33016f", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "uuids": { "description": "Specific demand. Omit to select by filter instead.", "type": "array", "items": { "type": "string" }, "nullable": true }, "urgent": { "description": "Only demand that has waited longer than the game's urgency threshold.", "type": "boolean", "nullable": true }, "at": { "description": "Departure ICAO.", "type": "string", "nullable": true }, "going_to": { "description": "Arrival ICAO. With `at`, this gives the internal \"between\" behaviour.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Released. A count of zero is a normal answer when nothing matched.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1DemandReleased" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:demand, or the role lacks release-collaborative-demand" }, "404": { "description": "No such company" }, "422": { "description": "No airport with that ICAO, or a malformed uuid in `uuids`" } }, "security": [ { "bearerAuth": [ "write:demand" ] } ] } }, "/api/v1/companies/{company}/dispatch-plans": { "get": { "tags": [ "Public API v1" ], "description": "Dispatch plans this company is drafting or has released. Use ?released=false for drafts still being built, ?released=true for published work.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "87dcc320a6e7ae3c3491e2f3164c6446", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "released", "in": "query", "description": "Narrow to drafts or to published plans.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1DispatchPlanResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Start a draft plan. A company may hold only ONE manual draft at a time, so this can hand back the draft already open rather than creating a second. Optionally attach demand straight away.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "fddff7dcce7dd670b0bef5e8a30b042a", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "demand": { "description": "Demand uuids to attach immediately. Can be set later with PUT /demand.", "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Created, or the existing open draft", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1DispatchPlanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/companies/{company}/finances": { "get": { "tags": [ "Public API v1" ], "description": "A company's bank balance, in pence.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "571aa5fc464842937aeff9baf67f51fe", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyFinancesResource" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, the token holder is not a member, or it has no bank account" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/groups": { "get": { "tags": [ "Public API v1" ], "description": "Named airport/country/aircraft sets this company reuses in filters and hireability rules.\n\n**Requires:** scope `read:operations`, plus the company privilege `view-groups`.", "operationId": "9f7f256839da3935089dc42c6429177d", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1GroupResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:operations, or the role lacks view-groups" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:operations" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Create a group. `identifiers` is capped at 100 per request — each one is validated against the database individually.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-groups`.", "operationId": "3d222594c55b9cd6688128d8c75662c2", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "type" ], "properties": { "name": { "type": "string" }, "type": { "type": "string", "enum": [ "airports", "countries", "aircraft" ] }, "identifiers": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1GroupResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-groups" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "Invalid name, type or identifier, or a premium-feature limit" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/companies/{company}/job-legs": { "get": { "tags": [ "Public API v1" ], "description": "A company's job legs — the flight board. Live legs by default; ?status= narrows, ?all=true includes history.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "8adbcea9a04057b0a9f1807668ca1248", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only legs with this status", "required": false, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "Include completed legs", "required": false, "schema": { "type": "boolean" } }, { "name": "partnership", "in": "query", "description": "Partnership code. Returns every member's legs rather than only this company's, which is the view an operations group watches. Verified against the caller's own partnerships.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobLegResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/companies/{company}/jobs": { "get": { "tags": [ "Public API v1" ], "description": "A company's jobs. Live jobs by default; ?status= narrows, ?all=true includes completed history.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "d0bfdea6d437905fe905bd8ea28f8d64", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only jobs with this status", "required": false, "schema": { "type": "string" } }, { "name": "all", "in": "query", "description": "Include completed jobs", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/companies/{company}/loan-products": { "get": { "tags": [ "Public API v1" ], "description": "The loans the game offers, and their terms. NOT your eligibility: the internal endpoint computes a maximum from net worth and AOC level per product, and states the exact net worth in its refusal text. Quote a loan to find out what you can actually borrow, which is authoritative at the moment you borrow it.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "7270ba25a5a7473b320d546b69adc470", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1LoanProductResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/loans": { "get": { "tags": [ "Public API v1" ], "description": "What this company owes. The transfer ceiling from GET /finances is the balance minus the full outstanding obligation across these, so this is what explains a ceiling lower than the balance. Settled loans are excluded unless you ask for them.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "a42987bdfa2d7f4886d605bb490f2ee8", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "settled", "in": "query", "description": "Set true to include loans already paid off.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1LoanResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Borrow money. Quote it first with POST /quotes using `for: loan`. The quote carries the EMI and the rates, and the loan is built from THOSE figures rather than the request's, so the rate a tool showed is the rate the company gets. Note that borrowing does not raise the transfer ceiling: that is the balance minus the full outstanding obligation.\n\n**Requires:** scope `write:finance`, plus the company privilege `view-finances`.", "operationId": "4f519df67f2d1cc22aa4f94b4002ef30", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "product", "amount", "term" ], "properties": { "quote": { "type": "string" }, "product": { "description": "Loan product uuid.", "type": "string" }, "amount": { "description": "Principal, in pence.", "type": "integer", "example": 50000000 }, "term": { "description": "Term in cycles.", "type": "integer", "example": 24 } }, "type": "object" } } } }, "responses": { "200": { "description": "Borrowed", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1LoanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:finance, or the role lacks view-finances" }, "404": { "description": "No such company or loan product" }, "422": { "description": "Refused: quote missing, spent, or priced for different terms; or the company cannot borrow this much" } }, "security": [ { "bearerAuth": [ "write:finance" ] } ] } }, "/api/v1/companies/{company}/loans/{loan}/repayments": { "post": { "tags": [ "Public API v1" ], "description": "Pay a loan down early. Quote it first with `for: loan-repayment`. Overpaying is CAPPED rather than refused, so a tool clearing a balance can send a round number without reading it first. Repaying frees transfer headroom, which is often the actual reason to call this.\n\n**Requires:** scope `write:finance`, plus the company privilege `view-finances`.", "operationId": "98c09182879efab9aa964b90d2edbc37", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "loan", "in": "path", "description": "Loan uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "amount" ], "properties": { "quote": { "type": "string" }, "amount": { "description": "In pence. More than the outstanding balance is capped, not refused.", "type": "integer", "example": 10000000 } }, "type": "object" } } } }, "responses": { "200": { "description": "Repaid", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1LoanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:finance, or the role lacks view-finances" }, "404": { "description": "No such company or loan" }, "422": { "description": "Refused: quote missing, spent, or priced for a different loan or amount; or the company cannot afford it" } }, "security": [ { "bearerAuth": [ "write:finance" ] } ] } }, "/api/v1/companies/{company}/my-roles": { "get": { "tags": [ "Public API v1" ], "description": "Which roles YOU hold here. No privilege beyond membership: a person may always ask what they themselves are allowed to do. Distinct from /privileges, which flattens the answer; this says which roles put you there, which is what you ask an admin to change.\n\n**Requires:** scope `read:people`, plus membership of the company.", "operationId": "0166a24fdf56979fa43e9a9b7c9b5043", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyRoleResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] } }, "/api/v1/companies/{company}/net-worth": { "get": { "tags": [ "Public API v1" ], "description": "What the company is worth: assets plus bank balance minus outstanding debt. A gate rather than a vanity number, because an aircraft transfer is refused if it would take net worth negative.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "d56bf3faee0acea8d6e2ca43e2367095", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1NetWorth" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/net-worth/assets": { "get": { "tags": [ "Public API v1" ], "description": "What makes up the net-worth figure, itemised. Each row carries the RECORDED value the check subtracts, which is not always the current market value, and that difference is what surprises people when a transfer is refused.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "1cbc7d9d179080919020cc8c4c45a177", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1NetWorthAssetResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/notams": { "get": { "tags": [ "Public API v1" ], "description": "Notices this company has posted for its own pilots.\n\n**Requires:** scope `read:operations`, plus the company privilege `manage-notams`.", "operationId": "09222d23273b10709549788fb2d8ad17", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1NotamResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:operations, or the role lacks manage-notams" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:operations" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Post a notice to the roster. Mails every active pilot on it, synchronously — a large roster makes this a genuinely slow call.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-notams`.", "operationId": "712ffd9ac40a1c6c1b3fc4dac70eaa32", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "title", "message" ], "properties": { "title": { "type": "string", "example": "Runway works at EGLL" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "announcement", "info", "important" ], "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Posted", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1NotamResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-notams" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "Title or message missing or too long, or an unrecognised type" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/companies/{company}/notification-preferences": { "get": { "tags": [ "Public API v1" ], "description": "Every notification this company can send, and whether you personally want it by email and in-game mail. Complete rather than sparse: notifications you have never touched report their own defaults with `is_default` true, so you never have to merge a second endpoint to answer \"will I be emailed about this?\".\n\n**Requires:** scope `read:profile`, plus membership of the company.", "operationId": "d0c843e857ef02ef01c50caf1dac8204", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1NotificationPreferenceResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:profile scope" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:profile" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Choose which notifications reach you and on which channels. Takes a list so a settings screen saves in one call; an omitted channel on an entry is left as it was. An unrecognised notification uuid is refused rather than ignored.\n\n**Requires:** scope `write:profile`, plus membership of the company.", "operationId": "c23ffda9024aadda3aae6a28258abca5", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "preferences" ], "properties": { "preferences": { "type": "array", "items": { "required": [ "notification" ], "properties": { "notification": { "description": "Notification uuid, from the GET.", "type": "string" }, "email": { "type": "boolean" }, "fsmail": { "type": "boolean" } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated — returns the full merged list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1NotificationPreferenceResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:profile scope" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "An unknown notification uuid, or an entry changing no channel" } }, "security": [ { "bearerAuth": [ "write:profile" ] } ] } }, "/api/v1/companies/{company}/notification-webhooks": { "patch": { "tags": [ "Public API v1" ], "description": "Set or clear the company-wide Discord webhook for one or more notifications. WRITE-ONLY: a webhook URL is a live credential, so no v1 endpoint returns one — not even this one. GET /notification-preferences reports only whether one is configured. Send null to clear. Must be a discord.com webhook URL.\n\n**Requires:** scope `write:profile`, plus the company privilege `update-global-notification-preferences`.", "operationId": "25edb41d56f56586d585f5a71ba65759", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "webhooks" ], "properties": { "webhooks": { "type": "array", "items": { "required": [ "notification", "discord_webhook" ], "properties": { "notification": { "type": "string" }, "discord_webhook": { "description": "A discord.com webhook URL, or null to clear.", "type": "string", "nullable": true } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated — a count, never the values", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1WebhooksUpdated" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:profile, or the role lacks update-global-notification-preferences" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "An unknown notification uuid, or a URL that is not a Discord webhook" } }, "security": [ { "bearerAuth": [ "write:profile" ] } ] } }, "/api/v1/companies/{company}/operations-centres": { "get": { "tags": [ "Public API v1" ], "description": "The company's bases. Their size and country are what building and agreement requirements are checked against.\n\n**Requires:** scope `read:base`, plus the company privilege `view-operations-centres`.", "operationId": "02a2018354148faaebdcf5c91fbb7ddc", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1OperationsCentreResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:base, or the role lacks view-operations-centres" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:base" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Open an operations centre at an airport. Usually the first thing a company buys somewhere, because buildings and agreements can require one of a minimum size in that country. Quote it first with `for: operations-centre`.\n\n**Requires:** scope `write:base`, plus the company privilege `purchase-operations-centres`.", "operationId": "9e90406ee76bb703479a0690919d4a1f", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "airport", "size" ], "properties": { "quote": { "type": "string" }, "airport": { "type": "string", "example": "EGCC" }, "size": { "type": "string", "enum": [ "micro", "small", "medium", "large", "huge" ], "example": "medium" } }, "type": "object" } } } }, "responses": { "200": { "description": "Opened", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1OperationsCentreResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks purchase-operations-centres" }, "404": { "description": "No such company" }, "422": { "description": "Refused: quote missing or spent, cannot afford it, or one already exists at that airport" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] } }, "/api/v1/companies/{company}/partnership-invitations/{partnership}/accept": { "post": { "tags": [ "Public API v1" ], "description": "Accept an invitation on your own company's behalf. Addressed at YOUR company rather than the partnership, because this is your company answering for itself.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `accept-partnership-invitations`.", "operationId": "2309817fa76a015df45e7169c6738409", "parameters": [ { "name": "company", "in": "path", "description": "Your company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Accepted", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PartnershipResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:partnerships, or the role lacks accept-partnership-invitations" }, "404": { "description": "No such company or partnership, or your company has no invitation to it" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/companies/{company}/partnership-invitations/{partnership}/decline": { "post": { "tags": [ "Public API v1" ], "description": "Decline an invitation. A separate privilege from accepting, matching the game: a role can be allowed to review offers without being able to commit the company to one.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `decline-partnership-invitations`.", "operationId": "ab7a9ebdb40780881090a93e1027fca3", "parameters": [ { "name": "company", "in": "path", "description": "Your company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Declined", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipInvitation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:partnerships, or the role lacks decline-partnership-invitations" }, "404": { "description": "No such company or partnership, or your company has no invitation to it" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/companies/{company}/partnerships": { "get": { "tags": [ "Public API v1" ], "description": "Alliances this company is in, INCLUDING ones it has been invited to and not yet answered. Pending ones are included on purpose: without them a tool cannot discover an invitation it is meant to accept, and accepting needs the partnership uuid.\n\n**Requires:** scope `read:partnerships`, plus the company privilege `view-partnerships`.", "operationId": "e6ffcb9b3604b45d671430bd51dd6e9f", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:partnerships, or the role lacks view-partnerships" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:partnerships" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Form an alliance. The creating company becomes the LEAD member, which is the only company that can then rename it, invite others, set revenue-sharing terms or dissolve it.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `create-partnerships`.", "operationId": "726cc4876e48eae68946264a82a2729c", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Silver Alliance" }, "code": { "description": "What other companies quote to find it. Must be unique across the game.", "type": "string", "nullable": true }, "colour": { "type": "string", "example": "#C0C0C0", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Formed", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PartnershipResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:partnerships, or the role lacks create-partnerships" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "The code is already taken" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/companies/{company}/partnerships/{partnership}/leave": { "post": { "tags": [ "Public API v1" ], "description": "Take your company out of an alliance. Your company's own decision, so it needs leave-partnerships at your company rather than anything at the lead member. The LEAD cannot leave: there would be nobody able to configure the alliance, so its exit is a dissolution.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `leave-partnerships`.", "operationId": "3c0cd4410be4534f2aa64d9fe3478321", "parameters": [ { "name": "company", "in": "path", "description": "Your company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipInvitation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:partnerships, or the role lacks leave-partnerships" }, "404": { "description": "No such company or partnership, or your company is not in it" }, "422": { "description": "Your company is the lead member. Dissolve the partnership instead." } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/companies/{company}/payments": { "get": { "tags": [ "Public API v1" ], "description": "The company's ledger, newest first. Filter with ?reference= to check whether a payment has already been made before making it again — this is the endpoint a payment queue reads for duplicate protection, and one filtered request replaces paging the whole history. Requires read:finance and the view-finances company privilege.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "7b3d1e8606e5152ad0b80bf55880e6be", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "reference", "in": "query", "description": "Exact match on the payment reference. The duplicate check.", "required": false, "schema": { "type": "string" } }, { "name": "direction", "in": "query", "description": "Only money leaving (outgoing) or arriving (incoming).", "required": false, "schema": { "type": "string", "enum": [ "incoming", "outgoing" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PaymentResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, the token holder is not a member, or it has no bank account" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/perspectives": { "get": { "tags": [ "Public API v1" ], "description": "Saved views of the operations cockpit.\n\n**Requires:** scope `read:operations`, plus the company privilege `use-perspectives`.", "operationId": "5e642382c04dfe9d64a9aaf64c2d51d5", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PerspectiveResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:operations, or the role lacks use-perspectives" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:operations" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "`data` is a plain JSON object — see PerspectiveResource for why that differs from the internal API. Its shape (lenses/filters/mapCamera) is validated deeply by the underlying action.\n\n**Requires:** scope `write:operations`, plus the company privilege `create-perspectives`.", "operationId": "cbf53cb667cb56f5f3bbc0e62d78f852", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "data" ], "properties": { "name": { "type": "string" }, "default": { "type": "boolean", "nullable": true }, "data": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PerspectiveResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks create-perspectives" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "Invalid name, a duplicate name, or an invalid data shape" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/companies/{company}/pricing-strategies": { "get": { "tags": [ "Public API v1" ], "description": "Standing discount rules this company runs. `state` collapses the underlying timestamps into one word, so a client does not have to compare paused_at, starts_at and ends_at against the clock to work out whether a strategy is applying.\n\n**Requires:** scope `read:routes`, plus the company privileges `view-routes`, `manage-pricing-strategies`.", "operationId": "7718f9c20ab3ad966a323df87a32035a", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PricingStrategyResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Start a discount rule. `discount` is a FRACTION, not a percentage: send 0.15 for fifteen per cent. The filter blocks pass through in the game's own selector shape, which is open-ended, so a new filter kind appears as a new key rather than a contract change.\n\n**Requires:** scope `write:routes`, plus the company privilege `manage-pricing-strategies`.", "operationId": "ab25f4582d205baebfa34855f691cd30", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "discount" ], "properties": { "discount": { "description": "A fraction between 0 and 1.", "type": "number", "format": "float", "example": 0.15 }, "name": { "type": "string", "nullable": true }, "route_filters": { "description": "Which routes it applies to.", "type": "object", "nullable": true }, "demand_filters": { "type": "object", "nullable": true }, "class_settings": { "description": "Per-cabin overrides.", "type": "object", "nullable": true }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "ends_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PricingStrategyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such company, or the token holder is not a member of it" }, "422": { "description": "Refused: discount out of range, dates inverted, or filters the engine cannot use" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/companies/{company}/privileges": { "get": { "tags": [ "Public API v1" ], "description": "What this TOKEN can do at this company: the role's privileges, the token's scopes, and the intersection of the two. Asking what you are allowed to do cannot itself need permission.\n\n**Requires:** scope `read:company`, plus membership of the company.", "operationId": "57d89770590fb97d6c72fd41328f9a85", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyPrivileges" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:company" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] } }, "/api/v1/companies/{company}/rank-progressions": { "get": { "tags": [ "Public API v1" ], "description": "The rank ladder as a set of edges: fly this many hours at rank A and rank B unlocks. Published as rank uuid pairs rather than nested ranks, so a client can assemble the graph after fetching the ranks once.\n\n**Requires:** scope `read:people`, plus the company privilege `view-pilot-roster`.", "operationId": "0630b873a12eb10e353211fa48c46b31", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RankProgressionResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-pilot-roster" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] } }, "/api/v1/companies/{company}/ranks": { "get": { "tags": [ "Public API v1" ], "description": "The ranks pilots fly under at this company, including the owner rank. Accepting a job needs one of these UUIDs.\n\n**Requires:** scope `read:company`, plus the company privilege `view-pilot-roster`.", "operationId": "9a26bde4397de93f21405e9350bde2ef", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyRankResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:company, or the role lacks view-pilot-roster" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Create a rank. Ranks are under write:roles rather than write:roster because a rank decides what a pilot may fly, which is a permission in everything but name.\n\n**Requires:** scope `write:roles`, plus the company privilege `create-ranks`.", "operationId": "e3b04bc3aa735db916f672d1806ee7bd", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name" ], "properties": { "name": { "type": "string", "example": "First Officer" }, "description": { "type": "string", "nullable": true }, "allow_application_from": { "description": "Minimum global rank level to apply.", "type": "integer", "nullable": true }, "auto_accept_from": { "description": "Global rank level at which applications are accepted automatically.", "type": "integer", "nullable": true }, "hourly_rate_pence": { "description": "In pence, like every money field in v1.", "type": "integer", "nullable": true }, "pay_interval_hours": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyRankResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks create-ranks" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/companies/{company}/recurring-payments": { "get": { "tags": [ "Public API v1" ], "description": "Standing costs: slot rents, loan repayments, salaries. Everything that leaves the account on a cycle whether or not the company flies.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "51137ec43e671e0e6bab05c4ba5e3bc0", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RecurringPaymentResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/recurring-payments/summary": { "get": { "tags": [ "Public API v1" ], "description": "The totals: one figure for what leaves the account each cycle, plus a split by what the money is for. Getting that sum right means knowing which payments are suspended, which is why it is an endpoint rather than arithmetic on the list.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "644eefd9d941fd4807ddd2701761f87e", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RecurringPaymentSummary" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/restriction-penalties": { "get": { "tags": [ "Public API v1" ], "description": "Legs re-priced down for spoilage: a group booking held too long before it flew, newest first.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "8c868e86a9b28c8c2c8059333f46729a", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RestrictionPenaltyResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/restriction-penalties/summary": { "get": { "tags": [ "Public API v1" ], "description": "Total pence lost to spoilage this calendar month, and how many legs it happened on.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "12a81ec907689394545cb8e8824389bd", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RestrictionPenaltySummary" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/companies/{company}/roles": { "get": { "tags": [ "Public API v1" ], "description": "The roles this company defines and the privilege slugs each grants. Behind view-role-details, because a role list is a map of who can do what.\n\n**Requires:** scope `read:people`, plus the company privilege `view-role-details`.", "operationId": "2d7d6a4ee0ad460c283cb76a42412700", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyRoleResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-role-details" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Create a role. It starts with no privileges; add them with PATCH /roles/{uuid}.\n\n**Requires:** scope `write:roles`, plus the company privilege `manage-roles`.", "operationId": "87d10230ce2e5a78516825c7397174a0", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "name", "colour", "icon" ], "properties": { "name": { "type": "string", "example": "Dispatcher" }, "colour": { "type": "string", "example": "#3B82F6" }, "icon": { "type": "string", "example": "fa-headset" }, "description": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyRoleResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks manage-roles" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/companies/{company}/roster": { "get": { "tags": [ "Public API v1" ], "description": "Pilots who fly for this company. `status` collapses the four underlying timestamps into one word so a client does not have to work out that an accepted entry which was later terminated is not active. ?status=pending is the applications queue and needs view-roster-applications rather than view-pilot-roster.\n\n**Requires:** scope `read:people`, plus the company privilege `view-pilot-roster`.", "operationId": "b1fe4c5e9ac0f512d4e4315506ad5074", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Defaults to active.", "required": false, "schema": { "type": "string", "enum": [ "active", "pending", "former" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RosterEntryResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-pilot-roster (view-roster-applications for ?status=pending)" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] } }, "/api/v1/companies/{company}/roster/applications/{pilot}/approve": { "post": { "tags": [ "Public API v1" ], "description": "Accept a pending application. Needs manage-roster-applications, which is separate from viewing the roster: seeing who flies for you is not the same as deciding who does.\n\n**Requires:** scope `write:roster`, plus the company privilege `manage-roster-applications`.", "operationId": "3878ce991109af3a9b2edf895e8a1529", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "pilot", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RosterEntryResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster, or the role lacks manage-roster-applications" }, "404": { "description": "No such company or pilot, or they have no pending application" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/roster/applications/{pilot}/reject": { "post": { "tags": [ "Public API v1" ], "description": "Decline a pending application.\n\n**Requires:** scope `write:roster`, plus the company privilege `manage-roster-applications`.", "operationId": "9b12e9be4aedde54102856c47872b8cd", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "pilot", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Rejected", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RosterEntryResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster, or the role lacks manage-roster-applications" }, "404": { "description": "No such company or pilot, or they have no pending application" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/roster/apply": { "post": { "tags": [ "Public API v1" ], "description": "Apply to fly for this company at a given rank. No privilege: applying is yours to do. Whether it auto-approves depends on the rank and your global rank, which the domain action decides.\n\n**Requires:** scope `write:roster`, plus membership of the company.", "operationId": "dbb25918b25755bfdc4f4b56302ae57b", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "rank" ], "properties": { "rank": { "description": "Rank uuid from GET /companies/{icao}/ranks.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Applied. Check `status`: it may already be active if the rank auto-accepts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RosterEntryResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster" }, "404": { "description": "No such company or rank" }, "422": { "description": "Refused: rank belongs to another company, global rank too low, or an application is already pending" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/roster/leave": { "post": { "tags": [ "Public API v1" ], "description": "Leave a roster yourself. Same mechanism as being removed, because in the game it is the same event with a different reason attached. No privilege: resigning is yours to do.\n\n**Requires:** scope `write:roster`, plus membership of the company.", "operationId": "05b8251f725956706b35bc1e570a64f5", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Left", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RosterEntryResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster" }, "404": { "description": "No such company, or you are not on its roster" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/roster/{pilot}": { "delete": { "tags": [ "Public API v1" ], "description": "Remove a pilot from the roster. `reason` is required and is recorded against them: it is the only record of why somebody was let go, and a tool doing this unattended should have to say.\n\n**Requires:** scope `write:roster`, plus the company privilege `remove-pilots-from-roster`.", "operationId": "fe251aca93feb022b8099a0b0346bb1b", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "pilot", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Inactive for 90 days" } }, "type": "object" } } } }, "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RosterEntryResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster, or the role lacks remove-pilots-from-roster" }, "404": { "description": "No such company or pilot, or they are not on the roster" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/route-numbers": { "get": { "tags": [ "Public API v1" ], "description": "Route numbers already in use at this company. Creating a route with one of these is refused, so this is how a tool picks a free one rather than guessing and retrying. Strings, not integers: route numbers are varchar and can carry a carrier prefix.\n\n**Requires:** scope `read:routes`, plus the company privilege `view-routes`.", "operationId": "bfe8259a97d86cf1a0d7349ea6aa44ca", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RouteNumbers" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks view-routes" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] } }, "/api/v1/companies/{company}/route-preview/{departure}/{arrival}": { "get": { "tags": [ "Public API v1" ], "description": "Demand on a pair you do not fly yet: \"is this route worth opening?\". Expensive — it builds a temporary route and its demand, then discards both — so it carries a tighter throttle than the rest of v1.\n\n**Requires:** scope `read:routes`, plus the company privileges `view-routes`, `view-route-demand`.", "operationId": "861e37862e6c56eaba7ede3560445b5c", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "departure", "in": "path", "description": "Departure airport ICAO", "required": true, "schema": { "type": "string" } }, { "name": "arrival", "in": "path", "description": "Arrival airport ICAO", "required": true, "schema": { "type": "string" } }, { "name": "economy_pence", "in": "query", "description": "Fare to preview at. Demand responds to price, so previewing at zero describes a route nobody would run.", "required": false, "schema": { "type": "integer" } }, { "name": "business_pence", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "first_pence", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RouteDemandPreview" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks view-route-demand" }, "404": { "description": "No such company or airport, or the token holder is not a member" }, "422": { "description": "Departure and arrival are the same airport" }, "429": { "description": "Preview throttle exceeded" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] } }, "/api/v1/companies/{company}/routes": { "get": { "tags": [ "Public API v1" ], "description": "A company's routes, with fares, minimums and a stable demand summary.\n\n**Requires:** scope `read:routes`, plus the company privilege `view-routes`.", "operationId": "9b2a4e458ab0bfdd9f063e78b30dcbc0", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RouteResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks view-routes" }, "404": { "description": "No such company, or the token holder is not a member" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Open a route between two airports. Fares and minimums default to zero, which accepts any booking; raising a minimum is how a company parks a route while demand accumulates. The slot and operations-centre requirements are checked by the domain action.\n\n**Requires:** scope `write:routes`, plus the company privilege `create-routes`.", "operationId": "583d6c97178503790851f683c30067e0", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "departure", "arrival" ], "properties": { "departure": { "type": "string", "example": "EGCC" }, "arrival": { "type": "string", "example": "EGLL" }, "number": { "description": "A string, and optional: the game assigns one when omitted.", "type": "string", "nullable": true }, "fares": { "description": "Per-cabin prices and booking minimums, all in pence and all optional.", "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Opened", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks create-routes" }, "404": { "description": "No such company or airport" }, "422": { "description": "Refused: the number is taken, the route already exists, or the company lacks the slots to fly it" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/companies/{company}/staff": { "get": { "tags": [ "Public API v1" ], "description": "People with a ROLE at this company, as opposed to the pilot roster, which is people who fly for it. Use ?pending=true for invitations not yet accepted.\n\n**Requires:** scope `read:people`, plus the company privilege `view-role-members`.", "operationId": "c739fa513f1f8417af445d8784b06c0e", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } }, { "name": "pending", "in": "query", "description": "Return unaccepted invitations instead of current staff.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1StaffResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-role-members" }, "404": { "description": "No such company, or the token holder is not a member of it" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "INVITE people to work here. They are not added until they accept, exactly as on the website: a token must not be able to conscript somebody into a company they never agreed to join.\n\n**Requires:** scope `write:roster`, plus the company privilege `hire-staff`.", "operationId": "39333e1b2865a53022c124d066a10007", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "usernames" ], "properties": { "usernames": { "type": "array", "items": { "type": "string" }, "example": [ "SirLoin" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PeopleChanged" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster, or the role lacks hire-staff" }, "404": { "description": "No such company, or one of the usernames does not exist" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Remove people from the company. Also strips every role they held here, which happens inside the domain action and is what makes firing meaningful.\n\n**Requires:** scope `write:roster`, plus the company privilege `fire-staff`.", "operationId": "a44888f05dd04122aa9882ae7a0468fc", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "usernames" ], "properties": { "usernames": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PeopleChanged" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster, or the role lacks fire-staff" }, "404": { "description": "No such company, or one of the usernames does not exist" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/staff/leave": { "post": { "tags": [ "Public API v1" ], "description": "Resign your own staff position. No privilege: this is a person acting on themselves, not the company acting on them.\n\n**Requires:** scope `write:roster`, plus membership of the company.", "operationId": "71848e5ebed13f10c658d16f24120e0e", "parameters": [ { "name": "company", "in": "path", "description": "Company ICAO", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Left", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1LeftCompany" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roster" }, "404": { "description": "No such company, or the token holder is not staff there" }, "422": { "description": "Refused: an owner cannot leave their own company" } }, "security": [ { "bearerAuth": [ "write:roster" ] } ] } }, "/api/v1/companies/{company}/transfers": { "post": { "tags": [ "Public API v1" ], "description": "Send money from this company to a pilot or another company. Subject to the same transferable ceiling as the website: outstanding loan obligations are reserved and the figure is bounded by the month's profit. Check GET /companies/{company}/finances first.\n\n**Requires:** scope `write:finance`, plus the company privilege `transfer-funds`.", "operationId": "930fb5c4dfd901d473404dc76593fd8c", "parameters": [ { "name": "company", "in": "path", "description": "Sending company ICAO", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "amount_pence" ], "properties": { "amount_pence": { "description": "Pence, like every money field in v1.", "type": "integer", "example": 500000 }, "to_pilot": { "description": "Recipient pilot username. Exactly one of to_pilot or to_company.", "type": "string", "example": "SirLoin" }, "to_company": { "description": "Recipient company ICAO. Exactly one of to_pilot or to_company.", "type": "string", "example": "BSC" }, "reference": { "description": "Shows on the payment, so the recipient can see what it was for.", "type": "string", "example": "Bounty: KSFO-YSSY in G-ABCD" } }, "type": "object" } } } }, "responses": { "200": { "description": "Sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1FundTransfer" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:finance, or the role lacks transfer-funds" }, "404": { "description": "No such company, or the token holder is not a member" }, "422": { "description": "Refused: over the transferable ceiling, company locked, no bank account, or sending to yourself. The message names which limit bound." } }, "security": [ { "bearerAuth": [ "write:finance" ] } ] } }, "/api/v1/company-directory": { "get": { "tags": [ "Public API v1" ], "description": "Every company in the game, not just the ones you are staff of. The same public directory the website shows. `?search=` matches name and ICAO.\n\n**Requires:** scope `read:company` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "5d255b9df0ecb69c06a3e5be3e951241", "parameters": [ { "name": "search", "in": "query", "description": "Matches company name and ICAO.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyDirectoryResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry read:company" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] } }, "/api/v1/company-exists": { "get": { "tags": [ "Public API v1" ], "description": "Is this ICAO already taken? Case-insensitive. Answers for every company, not just yours — this is what stops two people racing to incorporate the same code.\n\n**Requires:** scope `read:company` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "0e70a751eaca6102113db5bd5ccdc6c1", "parameters": [ { "name": "icao", "in": "query", "description": "The three-character code to check.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CompanyExists" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry read:company" }, "422": { "description": "No icao supplied" } }, "security": [ { "bearerAuth": [ "read:company" ] } ] } }, "/api/v1/constraint-types": { "get": { "tags": [ "Public API v1" ], "description": "The rank constraints a company can attach by hand. Mandatory and pilot-hidden constraint types are not listed, because a client can do nothing with them.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "c8975332a47ba0be282b2f9f5cda50a7", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1ConstraintTypeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/countries": { "get": { "tags": [ "Public API v1" ], "description": "Every country, keyed by ISO alpha-2. This is the `country` that the tail-number validator and country groups expect.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "7d66ea29b6e6e8bb52e8d5a1fef38c5f", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1CountryResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/demand": { "get": { "tags": [ "Public API v1" ], "description": "Passengers and cargo waiting to move. No company: the market is the same for everyone, and a company's jobs are what it chose to build out of it. Use ?collaborative=true to find work other companies have released to the pool.\n\n**Requires:** scope `read:demand` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "0d40cead62d1d932d068541e16eded89", "parameters": [ { "name": "departure", "in": "query", "description": "Departure ICAO.", "required": false, "schema": { "type": "string" } }, { "name": "arrival", "in": "query", "description": "Arrival ICAO.", "required": false, "schema": { "type": "string" } }, { "name": "collaborative", "in": "query", "description": "Narrow to demand that can be flown by another company.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1GroupDemandResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:demand" } }, "security": [ { "bearerAuth": [ "read:demand" ] } ] } }, "/api/v1/demand/{demand}": { "get": { "tags": [ "Public API v1" ], "description": "One piece of demand.\n\n**Requires:** scope `read:demand` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "79e4168c3737609f47aaebab4a1f655f", "parameters": [ { "name": "demand", "in": "path", "description": "Demand uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1GroupDemandResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:demand" }, "404": { "description": "No such demand" } }, "security": [ { "bearerAuth": [ "read:demand" ] } ] } }, "/api/v1/dispatch-plans/{plan}": { "get": { "tags": [ "Public API v1" ], "description": "One dispatch plan. `released` false means it is still a draft: editable, and invisible to pilots.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "fbf2cd761bf170a442edf0082c620710", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1DispatchPlanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such plan, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Throw a draft away.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `delete-dispatch-plans`.", "operationId": "a50ff714bceabd038bca3b24814e882a", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks delete-dispatch-plans" }, "404": { "description": "No such plan, or the token holder is not a member of its company" }, "422": { "description": "Refused: the plan is released and its jobs are in progress" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/demand": { "put": { "tags": [ "Public API v1" ], "description": "Set the FULL set of demand this plan carries. A replacement rather than an add: the internal API also offers add and remove, but only replacement is safe for a client, because add-and-remove needs knowledge of the current contents that may be stale by the time the request lands. An empty array means carry nothing.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "a09d761b8441d604effe18fb15fb43d0", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "demand" ], "properties": { "demand": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1DispatchPlanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such plan, or one of the demand uuids does not exist" }, "422": { "description": "Refused: the plan is already released, or the demand cannot be carried" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/jobs": { "get": { "tags": [ "Public API v1" ], "description": "The jobs inside a plan, in the same shape as every other job list in v1.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "3eac353436e68e4639a7cf8a8666facd", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such plan, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Add a job to a draft, built FROM demand legs. The game works out the route from the legs, which is why this names leg uuids rather than airports. Legs must belong to this plan.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "83075a72ae2d0476ca6883a0ab39ac18", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "demand_legs" ], "properties": { "demand_legs": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such plan" }, "422": { "description": "One or more demand legs are not part of this plan, or the job cannot be built from them" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/jobs/{job}": { "delete": { "tags": [ "Public API v1" ], "description": "Take a job back out of a draft. Once the plan is released a pilot may have accepted the job, and removing it from under them is a different act: POST /jobs/{uuid}/reset.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "6eb784cfbfb42d2934122871d79fe6be", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such plan or job" }, "422": { "description": "That job is not part of this plan, or the plan is released" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/jobs/{job}/legs": { "post": { "tags": [ "Public API v1" ], "description": "Add an EMPTY positioning leg to a job: a hop that carries nothing, used to get an aircraft where the next paying leg starts. That is why it names two airports rather than demand.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "8be13ac5f9a72144f8e68ad5e43abc84", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "from", "to" ], "properties": { "from": { "type": "string", "example": "EGCC" }, "to": { "type": "string", "example": "EGLL" } }, "type": "object" } } } }, "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobLegResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such plan, job or airport" }, "422": { "description": "That job is not part of this plan, or the leg cannot be added" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/jobs/{job}/legs/{leg}": { "delete": { "tags": [ "Public API v1" ], "description": "Remove a leg from a job in a draft. Every parent is checked rather than trusted from the path, so a leg cannot be reached by nesting it under a plan you happen to own.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "f7d708c647c5d9c408582f027f99e8cb", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } }, { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } }, { "name": "leg", "in": "path", "description": "Job leg uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such plan, job or leg" }, "422": { "description": "The job is not part of this plan, or the leg is not part of this job" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/dispatch-plans/{plan}/released": { "patch": { "tags": [ "Public API v1" ], "description": "Publish a plan to your pilots, or pull it back. The most consequential write in this scope: releasing is the moment work becomes visible and acceptable. One endpoint with a boolean rather than /release and /un-release, so a tool reconciling desired state need not pick a URL from a state it has not read. Asking for the state it is already in is answered rather than refused.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `release-dispatch-plans`.", "operationId": "4bb593eeb1b985ba61ad844ca3e1b696", "parameters": [ { "name": "plan", "in": "path", "description": "Dispatch plan uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "released" ], "properties": { "released": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1DispatchPlanResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks release-dispatch-plans" }, "404": { "description": "No such plan, or the token holder is not a member of its company" }, "422": { "description": "Refused: the plan has nothing to release, or a released job is already in progress" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/groups/{group}": { "put": { "tags": [ "Public API v1" ], "description": "Update a group. `identifiers`, if supplied, REPLACES the group's contents — there is no add/remove, so send the full list back.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-groups`.", "operationId": "442f44f29f2b276b4fd2bc0ddb48641e", "parameters": [ { "name": "group", "in": "path", "description": "Group uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string" }, "identifiers": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1GroupResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-groups" }, "404": { "description": "No such group, or the token holder is not a member of its company" }, "422": { "description": "Invalid name or identifier, or a premium-feature limit" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Delete a group. Also removes it from any rank constraint that referenced it.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-groups`.", "operationId": "d4646e4090527e3f712cc7d7246d6c9b", "parameters": [ { "name": "group", "in": "path", "description": "Group uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-groups" }, "404": { "description": "No such group, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/hire-aircraft": { "post": { "tags": [ "Public API v1" ], "description": "Hire another player's aircraft and fly the demand you name on it. This creates the job and puts you on it. The one v1 write with no company: you hire as yourself, so there is no company role to check, only the token scope.\n\n**Requires:** scope `write:market` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "b572a99c7d165cf4a45a437a2d2ab60d", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "aircraft", "group_demand_uuids" ], "properties": { "aircraft": { "description": "Tail number, from GET /hireable-aircraft.", "type": "string", "example": "G-ABCD" }, "group_demand_uuids": { "description": "The demand to carry.", "type": "array", "items": { "type": "string" } }, "rank_uuid": { "description": "Required where the aircraft is rank-gated. From GET /aircraft/{registration}/available-ranks.", "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Hired. Check `pending_roster_application` first: when true, you have applied for the rank and no job exists yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1HireResult" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:market" }, "404": { "description": "No such aircraft or rank" }, "422": { "description": "Refused: not hireable by you, demand already taken, or your rank cannot fly this aircraft" } }, "security": [ { "bearerAuth": [ "write:market" ] } ] } }, "/api/v1/hireable-aircraft": { "get": { "tags": [ "Public API v1" ], "description": "Aircraft other players are offering for hire that YOU could actually fly. Rank constraints and charter-readiness (not frozen, not in service, no overdue checks, has a position) are already applied, so there is no need to filter this again.\n\n**Requires:** scope `read:market` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "299127703a31a293d4ab43584ca39119", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1HireableAircraftResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:market" } }, "security": [ { "bearerAuth": [ "read:market" ] } ] } }, "/api/v1/job-legs/{jobLeg}": { "get": { "tags": [ "Public API v1" ], "description": "One leg: where it went, in what, flown by whom, and when it landed.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "f00cba2b44c1c50b7084c56c96b2d783", "parameters": [ { "name": "jobLeg", "in": "path", "description": "Job leg UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobLegResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such leg, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}": { "get": { "tags": [ "Public API v1" ], "description": "One job with its legs. No financial fields — see /jobs/{job}/revenue.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "4205c49590e45dedc1d121a66ee915a1", "parameters": [ { "name": "job", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/accept": { "post": { "tags": [ "Public API v1" ], "description": "Take a job onto one of your aircraft. Name the aircraft by a registration from GET /jobs/{job}/eligible-aircraft, which exists so this is not guesswork.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `create-dispatch-plans`.", "operationId": "fda03a93bb7f8b7fe4c6d0d1eab8e5a8", "parameters": [ { "name": "job", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "aircraft" ], "properties": { "aircraft": { "description": "Tail number, from GET /jobs/{job}/eligible-aircraft.", "type": "string", "example": "G-ABCD" }, "rank": { "description": "Rank UUID to fly under. Defaults to your own rank at the company.", "type": "string" }, "ferry": { "description": "Repositioning an empty aircraft. Needs the ferry privilege.", "type": "boolean", "example": false } }, "type": "object" } } } }, "responses": { "200": { "description": "Accepted — returns the job", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks create-dispatch-plans" }, "404": { "description": "No such job, or the token holder is not a member of its company" }, "422": { "description": "Refused: the aircraft is not yours, not eligible, not in position, or the job is gone, or a route load falls short of its passenger, cargo or freight minimums" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/jobs/{job}/constraints": { "get": { "tags": [ "Public API v1" ], "description": "WHY you cannot accept this job. The complement of /eligible-aircraft: that says which planes could fly it, this says what is stopping you. Runs the same evaluator the accept flow uses, so it cannot disagree with the thing that actually refuses.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "8875727f41e160124b48eb28a7eef1dd", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobConstraints" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/demand": { "get": { "tags": [ "Public API v1" ], "description": "What this job is carrying: the link between the job and the market it was built from. A bounty check confirming a delivery wants to know what was actually on board, not only that a leg was flown.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "5c31da28cf857c88fde7db2dae0255d1", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1GroupDemandResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/eligible-aircraft": { "get": { "tags": [ "Public API v1" ], "description": "Which of your aircraft may fly this job, per your rank's constraints.\n\n**Requires:** scope `read:jobs`, plus the company privileges `view-dispatch-plans`, `view-aircraft`.", "operationId": "130a54a24a4c06426b1c2400464b6b0c", "parameters": [ { "name": "job", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string" } }, { "name": "rank", "in": "query", "description": "Rank UUID to test against. Defaults to your own rank at the company.", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-aircraft" }, "404": { "description": "No such job, or the token holder is not a member of its company" }, "422": { "description": "The caller has no rank at this company and named none" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/prerequisites": { "get": { "tags": [ "Public API v1" ], "description": "What must be flown before this job can be. Collaborative chains are only flyable in order, so a tool planning a day needs the dependency picture rather than a flat list.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "6bb6b7dfd9586bf0dd4eb847360c76f4", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobPrerequisites" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-dispatch-plans" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/release-early": { "post": { "tags": [ "Public API v1" ], "description": "Let a job be flown before its prerequisites are met. Collaborative chains are normally flown in order, each leg waiting for the one feeding it; this overrides that for one job, which is why it has its own privilege. Note it can leave a downstream leg carrying demand that never arrived.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `release-jobs-early`.", "operationId": "7f71a3fb43e75475f7f60898f61d190d", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Released", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks release-jobs-early" }, "404": { "description": "No such job, or the token holder is not a member of its company" }, "422": { "description": "Refused: the job has no unmet prerequisites, or is not in a releasable state" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/jobs/{job}/reset": { "post": { "tags": [ "Public API v1" ], "description": "Take a job back off the pilot who accepted it. Behind cancel-active-jobs rather than the dispatch privilege, because somebody may be part-way through flying it. `reason` is required and is the only explanation the pilot gets.\n\n**Requires:** scope `write:jobs`, plus the company privileges `view-dispatch-plans`, `cancel-active-jobs`.", "operationId": "dc6f0698e71024909f906ec5e38efc88", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "reason" ], "properties": { "reason": { "type": "string", "example": "Aircraft reassigned" } }, "type": "object" } } } }, "responses": { "200": { "description": "Reset", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1JobResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:jobs, or the role lacks cancel-active-jobs" }, "404": { "description": "No such job, or the token holder is not a member of its company" }, "422": { "description": "Refused: the job is airborne or already complete" } }, "security": [ { "bearerAuth": [ "write:jobs" ] } ] } }, "/api/v1/jobs/{job}/revenue": { "get": { "tags": [ "Public API v1" ], "description": "What a job has earned and what it has not earned yet.\n\n**Requires:** scope `read:jobs`, plus the company privileges `view-dispatch-plans`, `view-job-details`.", "operationId": "3901e0ebd1bafe96c45602dad529bb42", "parameters": [ { "name": "job", "in": "path", "description": "Job UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobRevenue" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-job-details" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/jobs/{job}/unlocked-revenue": { "get": { "tags": [ "Public API v1" ], "description": "How much of the job's revenue has actually been unlocked by legs already flown. DIFFERENT from /jobs/{uuid}/revenue, which is what the job is worth in total: on a multi-leg job the two diverge for most of its life, and a tool paying per completed leg wants this one.\n\n**Requires:** scope `read:jobs`, plus the company privileges `view-dispatch-plans`, `view-job-details`.", "operationId": "7f31378a3ea5cab1b94b4ce0529d5a40", "parameters": [ { "name": "job", "in": "path", "description": "Job uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1UnlockedRevenue" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs, or the role lacks view-job-details" }, "404": { "description": "No such job, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/mail": { "get": { "tags": [ "Public API v1" ], "description": "Your mailbox, newest first. `?folder=archived` returns what you have filed away; the default is the inbox.\n\n**Requires:** scope `read:mail` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "631b65fbb8ecb8b93c417b93e65c7e6a", "parameters": [ { "name": "folder", "in": "query", "description": "inbox (default) or archived.", "required": false, "schema": { "type": "string", "enum": [ "inbox", "archived" ] } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1MailMessageResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:mail scope" } }, "security": [ { "bearerAuth": [ "read:mail" ] } ] } }, "/api/v1/mail/archive-all": { "post": { "tags": [ "Public API v1" ], "description": "Move everything in your inbox to the archive. Nothing is deleted: archived mail is readable at ?folder=archived and can be brought back one message at a time.\n\n**Requires:** scope `write:mail` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "3392916d1049bc80a88f981f38da3506", "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1UnreadMailCount" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:mail scope" } }, "security": [ { "bearerAuth": [ "write:mail" ] } ] } }, "/api/v1/mail/read-all": { "post": { "tags": [ "Public API v1" ], "description": "Mark every message in your inbox as read. Returns the new unread count, which will be zero.\n\n**Requires:** scope `write:mail` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "ac2b865e2640ee797b7211ff82273202", "responses": { "200": { "description": "Done", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1UnreadMailCount" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:mail scope" } }, "security": [ { "bearerAuth": [ "write:mail" ] } ] } }, "/api/v1/mail/unread-count": { "get": { "tags": [ "Public API v1" ], "description": "How many unread messages are in your inbox. Archived messages are not counted even if they were never read, matching the badge the website shows.\n\n**Requires:** scope `read:mail` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "e4673c745e48c526efcd271568ae4e7d", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1UnreadMailCount" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:mail scope" } }, "security": [ { "bearerAuth": [ "read:mail" ] } ] } }, "/api/v1/mail/{message}": { "patch": { "tags": [ "Public API v1" ], "description": "File one message: mark it read or unread, archive it or bring it back. One endpoint with two flags, replacing four internal verbs. Both fields optional and idempotent — asking for the state it is already in is answered, not refused.\n\n**Requires:** scope `write:mail` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "9bf793c0263215d1a0de2a4ea03eb614", "parameters": [ { "name": "message", "in": "path", "description": "Message uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "read": { "type": "boolean" }, "archived": { "type": "boolean" } }, "type": "object" } } } }, "responses": { "200": { "description": "Filed", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1MailMessageResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:mail scope" }, "404": { "description": "No such message, or you are not its recipient" }, "422": { "description": "Neither read nor archived supplied" } }, "security": [ { "bearerAuth": [ "write:mail" ] } ] } }, "/api/v1/me": { "get": { "tags": [ "Public API v1" ], "description": "The authenticated token holder's own profile: identity, flying record and account state.\n\n**Requires:** scope `read:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "a1fa9090ac4490c43338ef0db5a90945", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1MeResource" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:profile scope" } }, "security": [ { "bearerAuth": [ "read:profile" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change your own name or email. IMPORTANT: an email change does NOT take effect here. It sends a verification link, and the address only moves once that link is followed from the inbox — so a 200 means \"we have sent the email\". Watch `pending_email` on GET /me to see a change still in flight. Avatar upload is not exposed.\n\n**Requires:** scope `write:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "ba3760682782f713ce8d750a937b8c7e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "description": "Triggers a verification email. Does not change the account by itself.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated. An email change is pending verification.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1MeResource" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:profile scope" }, "422": { "description": "Nothing supplied, or the email is already taken" } }, "security": [ { "bearerAuth": [ "write:profile" ] } ] } }, "/api/v1/me/preferences": { "get": { "tags": [ "Public API v1" ], "description": "Your settings as a flat map of dotted key to value. Every preference the game has is present, whether or not you have changed it.\n\n**Requires:** scope `read:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "6021db1a0753303581af40737f7c448f", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Preferences" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:profile scope" } }, "security": [ { "bearerAuth": [ "read:profile" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change one or more settings. Partial: only the keys you send change, and the response is the full map. Keys and values are checked against the game's own catalogue, so an unrecognised key is refused rather than silently stored.\n\n**Requires:** scope `write:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "dacc9c96d83ece41f3820cfa3580adba", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "preferences" ], "properties": { "preferences": { "description": "Dotted key to value. See GET /me/preferences for the keys.", "type": "object", "example": { "units.weight": "lb" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Preferences" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the write:profile scope" }, "422": { "description": "An unrecognised key, or a value that key does not accept" } }, "security": [ { "bearerAuth": [ "write:profile" ] } ] } }, "/api/v1/me/simbrief": { "get": { "tags": [ "Public API v1" ], "description": "Your SimBrief flight-planner settings: passenger weight in kilograms, and which SimBrief airframe to use for a given tail number or aircraft type.\n\n**Requires:** scope `read:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "ae4fed4fdacffb4dcfffaf6a902163b7", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1SimbriefResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:profile scope" } }, "security": [ { "bearerAuth": [ "read:profile" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change your SimBrief settings. `airframe_mappings`, when supplied, REPLACES the whole list — omit it to leave the mappings alone, or send an empty array to clear them. Airframe mapping is a premium feature.\n\n**Requires:** scope `write:profile` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "a757c7a1592bddd451a54eac160ca1a8", "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "passenger_weight_kg": { "type": "number", "format": "float", "example": 84 }, "airframe_mappings": { "type": "array", "items": { "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1SimbriefResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:profile, or the account lacks the premium feature" }, "422": { "description": "Nothing supplied, or a weight outside 30-150kg" } }, "security": [ { "bearerAuth": [ "write:profile" ] } ] } }, "/api/v1/my-jobs": { "get": { "tags": [ "Public API v1" ], "description": "What YOU are currently flying, across every company. No company in the path, because the question is about the person: somebody flying for four airlines wants one list rather than four requests to merge.\n\n**Requires:** scope `read:jobs`, plus the company privilege `view-dispatch-plans`.", "operationId": "e87729f5fd227e092cb864856a815ec2", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:jobs" } }, "security": [ { "bearerAuth": [ "read:jobs" ] } ] } }, "/api/v1/notams/{notam}": { "delete": { "tags": [ "Public API v1" ], "description": "Delete a NOTAM.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-notams`.", "operationId": "5fa2bcb7baa09e39ff280c9d2f48378f", "parameters": [ { "name": "notam", "in": "path", "description": "NOTAM uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-notams" }, "404": { "description": "No such NOTAM, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Edit a NOTAM. Every field optional; only what is supplied changes.\n\n**Requires:** scope `write:operations`, plus the company privilege `manage-notams`.", "operationId": "a7b43b15cb0db32659426416acd93df4", "parameters": [ { "name": "notam", "in": "path", "description": "NOTAM uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "title": { "type": "string" }, "message": { "type": "string" }, "type": { "type": "string", "enum": [ "announcement", "info", "important" ] } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1NotamResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks manage-notams" }, "404": { "description": "No such NOTAM, or the token holder is not a member of its company" }, "422": { "description": "Title or message too long, or an unrecognised type" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/operations-centres/{operationsCentre}": { "delete": { "tags": [ "Public API v1" ], "description": "Close an operations centre. The most consequential delete in the estate: buildings and agreements at that airport may require one of a minimum size, so closing it can invalidate holdings that were legal a moment earlier. Quoted, like every sale.\n\n**Requires:** scope `write:base`, plus the company privilege `sell-operations-centres`.", "operationId": "83f33e9a00bb7adb8efc6389581fc512", "parameters": [ { "name": "operationsCentre", "in": "path", "description": "Operations centre uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote" ], "properties": { "quote": { "description": "Quote uuid from POST /api/v1/quotes with `for: operations-centre-sale`.", "type": "string" } }, "type": "object" } } } }, "responses": { "200": { "description": "Closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1EstateSale" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks sell-operations-centres" }, "404": { "description": "No such operations centre, or the token holder is not a member of its company" }, "422": { "description": "Refused: quote missing or spent, or holdings at this airport still depend on it" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Grow an operations centre. The only thing in the estate that upgrades in place, which is why PATCH means something different here from PATCH on a building. Upwards only. Quote it first with `for: operations-centre-upgrade`.\n\n**Requires:** scope `write:base`, plus the company privilege `upgrade-operations-centres`.", "operationId": "bb235621b97c12852822d8192e23216c", "parameters": [ { "name": "operationsCentre", "in": "path", "description": "Operations centre uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "quote", "size" ], "properties": { "quote": { "type": "string" }, "size": { "description": "Must be larger than the current size.", "type": "string", "enum": [ "micro", "small", "medium", "large", "huge" ], "example": "large" } }, "type": "object" } } } }, "responses": { "200": { "description": "Upgraded", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1OperationsCentreResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:base, or the role lacks upgrade-operations-centres" }, "404": { "description": "No such operations centre, or the token holder is not a member of its company" }, "422": { "description": "Refused: quote missing or spent, cannot afford it, or the size is not an upgrade" } }, "security": [ { "bearerAuth": [ "write:base" ] } ] } }, "/api/v1/partnerships/{partnership}": { "get": { "tags": [ "Public API v1" ], "description": "One alliance. Addressed by uuid rather than nested under a company, because a partnership is not owned by one. Readable with view-partnerships at any member company.\n\n**Requires:** scope `read:partnerships`, plus the company privilege `view-partnerships`.", "operationId": "e806251d5e90d49fad70667b9539c9fd", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PartnershipResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:partnerships" }, "404": { "description": "No such partnership, or the token holder is not a member of any company in it" } }, "security": [ { "bearerAuth": [ "read:partnerships" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "End the alliance for EVERYBODY. Not the same as leaving: leaving removes your company, this ends it for every member, which is why only the lead can and why it carries delete-partnerships rather than leave-partnerships.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `delete-partnerships`.", "operationId": "f7b8ceff7382bd869635384a75f13f92", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Dissolved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipDissolved" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks delete-partnerships" }, "404": { "description": "No such partnership, or the token holder is not a member of any company in it" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Rename or recolour an alliance, or change its join code. LEAD MEMBER ONLY: if any member could, a junior partner could rename the alliance out from under everybody.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `update-partnerships`.", "operationId": "0c113afc1af1dbfec439ce2156226df2", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true }, "code": { "type": "string", "nullable": true }, "colour": { "type": "string", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PartnershipResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks update-partnerships" }, "404": { "description": "No such partnership, or the token holder is not a member of any company in it" }, "422": { "description": "The code is already taken" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/partnerships/{partnership}/invitations": { "post": { "tags": [ "Public API v1" ], "description": "Ask a company to join. An INVITATION: they have to accept, so a token cannot enrol somebody else's airline into an alliance it never agreed to. The percentages are the terms being offered and are optional, because an alliance may not have revenue sharing on at all.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `invite-partnership-members`.", "operationId": "f329e898f91a180d6edc084adb13550d", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "company" ], "properties": { "company": { "description": "ICAO of the company to invite.", "type": "string", "example": "BSC" }, "contribution_percentage": { "type": "number", "format": "float", "nullable": true }, "share_percentage": { "type": "number", "format": "float", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Invited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipInvitation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks invite-partnership-members" }, "404": { "description": "No such partnership or company" }, "422": { "description": "Already invited or already a member" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/partnerships/{partnership}/invitations/{company}": { "delete": { "tags": [ "Public API v1" ], "description": "Withdraw an outstanding offer. Only reaches PENDING invitations; removing a company that already joined is DELETE /partnerships/{uuid}/members/{icao}, which needs a different privilege.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `invite-partnership-members`.", "operationId": "4e2f5c14748412d5d03bd73268f9095f", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } }, { "name": "company", "in": "path", "description": "ICAO of the invited company", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipInvitation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks invite-partnership-members" }, "404": { "description": "No such partnership or company" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/partnerships/{partnership}/members": { "get": { "tags": [ "Public API v1" ], "description": "Who is in the alliance and on what terms. `contribution_percentage` is what a company puts IN and `share_percentage` is what it takes OUT: they are set independently, so neither can be derived from the other. Use ?pending=true for invitations not yet answered.\n\n**Requires:** scope `read:partnerships`, plus the company privilege `view-partnerships`.", "operationId": "7bb7799138b7d56a0fcb3fed15c5d7dc", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } }, { "name": "pending", "in": "query", "description": "Return outstanding invitations instead of members.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipMemberResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:partnerships" }, "404": { "description": "No such partnership, or the token holder is not a member of any company in it" } }, "security": [ { "bearerAuth": [ "read:partnerships" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Set revenue-sharing terms for every member at once. BULK on purpose: the percentages describe how one pot is divided, so they are interdependent and a per-company endpoint would let a client leave the split inconsistent one request at a time.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `update-partnerships`.", "operationId": "8d64dc51bc04c2ec92df507962a4783f", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "members" ], "properties": { "members": { "type": "array", "items": { "required": [ "icao", "contribution_percentage", "share_percentage" ], "properties": { "icao": { "type": "string", "example": "BSC" }, "contribution_percentage": { "type": "number", "format": "float", "example": 25 }, "share_percentage": { "type": "number", "format": "float", "example": 30 } }, "type": "object" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated — returns every member on its new terms", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipMemberResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks update-partnerships" }, "404": { "description": "No such partnership" }, "422": { "description": "A named company is not in this partnership, or the percentages are not acceptable" } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/partnerships/{partnership}/members/{company}": { "delete": { "tags": [ "Public API v1" ], "description": "Remove a company that had joined. Distinct from revoking an invitation (never joined) and from a company leaving (its own decision). The lead member cannot be removed this way: dissolve the partnership instead.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `remove-partnership-members`.", "operationId": "aac39547ff01f8541c4473127fdb7276", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } }, { "name": "company", "in": "path", "description": "ICAO of the member to remove", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PartnershipInvitation" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks remove-partnership-members" }, "404": { "description": "No such partnership or company" }, "422": { "description": "That company is the lead member. Dissolve the partnership instead." } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/partnerships/{partnership}/revenue-sharing": { "patch": { "tags": [ "Public API v1" ], "description": "Turn revenue sharing on or off. One endpoint with a boolean rather than two paths, so a tool mirroring a toggle need not pick a URL from a state it has not read. Note that disabling is not instant: `pending_cleanup` stays true while in-flight collaborative bookkeeping settles.\n\n**Requires:** scope `write:partnerships`, plus the company privilege `update-partnerships`.", "operationId": "418d1e66a543e8b0aba9729ee6c525cb", "parameters": [ { "name": "partnership", "in": "path", "description": "Partnership uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean", "example": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Set. Asking for the state it is already in is answered rather than refused.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RevenueSharing" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Not the lead member, or the role there lacks update-partnerships" }, "404": { "description": "No such partnership" }, "422": { "description": "`enabled` is required. It is never defaulted, because silently disabling would change what every member earns." } }, "security": [ { "bearerAuth": [ "write:partnerships" ] } ] } }, "/api/v1/payments/{payment}/items": { "get": { "tags": [ "Public API v1" ], "description": "The line items behind one payment. A flight's revenue arrives in the ledger as a single row; this is the fuel, landing fees, ATC and crew underneath it. Readable by staff of either side of the payment.\n\n**Requires:** scope `read:finance`, plus the company privilege `view-finances`.", "operationId": "176c19cbb6d74c73346dd68759ac7dab", "parameters": [ { "name": "payment", "in": "path", "description": "Payment uuid, from the ledger", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PaymentItemResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:finance, or the role lacks view-finances" }, "404": { "description": "No such payment, or the token holder is not staff of either side of it" } }, "security": [ { "bearerAuth": [ "read:finance" ] } ] } }, "/api/v1/perspectives/{perspective}": { "delete": { "tags": [ "Public API v1" ], "description": "Delete a saved perspective. Refused if it is the company's current default — set a different one first.\n\n**Requires:** scope `write:operations`, plus the company privilege `delete-perspectives`.", "operationId": "a651a447b3f1fc3e80122e56fa69ab4a", "parameters": [ { "name": "perspective", "in": "path", "description": "Perspective uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks delete-perspectives" }, "404": { "description": "No such perspective, or the token holder is not a member of its company" }, "422": { "description": "Refused: this is the company's default perspective" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Make this the company's default perspective. There is no endpoint to rename or edit a saved perspective's contents — the game has no such action.\n\n**Requires:** scope `write:operations`, plus the company privilege `set-default-perspective`.", "operationId": "5fa52ed47e31919534e65a909b4be280", "parameters": [ { "name": "perspective", "in": "path", "description": "Perspective uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Now the default", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PerspectiveResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:operations, or the role lacks set-default-perspective" }, "404": { "description": "No such perspective, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:operations" ] } ] } }, "/api/v1/pilots/{user}/achievements": { "get": { "tags": [ "Public API v1" ], "description": "A player's achievement progress. Secret achievements they have not unlocked report a null name and description. Only achievements with recorded progress appear — unlike the website, reading a profile here does not create progress rows for the person being looked at.\n\n**Requires:** scope `read:pilots` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "e7c2a19188b0b68c3c9800b13fcdc227", "parameters": [ { "name": "user", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PilotAchievementResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:pilots scope" }, "404": { "description": "No player with that username" } }, "security": [ { "bearerAuth": [ "read:pilots" ] } ] } }, "/api/v1/pilots/{user}/logbook": { "get": { "tags": [ "Public API v1" ], "description": "A player's logged flights, newest first. Every field is a snapshot taken when the flight was logged, so entries keep reading correctly after the company is wound up or the aircraft sold.\n\n**Requires:** scope `read:pilots` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "32310b7259557d91dd14fcdaab08929c", "parameters": [ { "name": "user", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PilotLogbookResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:pilots scope" }, "404": { "description": "No player with that username" } }, "security": [ { "bearerAuth": [ "read:pilots" ] } ] } }, "/api/v1/pilots/{user}/statistics": { "get": { "tags": [ "Public API v1" ], "description": "A player's public flying record: rank, total flights and hours by aircraft category. The same shape as the flying half of GET /me, so one component can render either.\n\n**Requires:** scope `read:pilots` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "462516d55f7fde18f8bbbb14b2ead245", "parameters": [ { "name": "user", "in": "path", "description": "Username", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PilotStatisticsResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:pilots scope" }, "404": { "description": "No player with that username" } }, "security": [ { "bearerAuth": [ "read:pilots" ] } ] } }, "/api/v1/pricing-strategies/{strategy}": { "get": { "tags": [ "Public API v1" ], "description": "One strategy. The internal API splits this into /{uuid} and /{uuid}/details; v1 publishes one endpoint, because the filters are the only thing that makes a strategy comprehensible and splitting them forced two round trips to answer \"what does this actually do\".\n\n**Requires:** scope `read:routes`, plus the company privileges `view-routes`, `manage-pricing-strategies`.", "operationId": "b2e24dcc02d89f01765b602b2839e5cc", "parameters": [ { "name": "strategy", "in": "path", "description": "Pricing strategy uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PricingStrategyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such strategy, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Remove a strategy entirely. Different from ENDING one: ending stops it applying but keeps the record, so what a company was charging stays readable. A tool tidying up almost always wants to end rather than delete.\n\n**Requires:** scope `write:routes`, plus the company privilege `manage-pricing-strategies`.", "operationId": "39d0bd3a24f08dbff482c0300c37be97", "parameters": [ { "name": "strategy", "in": "path", "description": "Pricing strategy uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such strategy, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change a rule's terms. Every field optional, omitted means unchanged. Note that changing the filters changes which routes the discount applies to, so this can move fares on routes you never named.\n\n**Requires:** scope `write:routes`, plus the company privilege `manage-pricing-strategies`.", "operationId": "091e31995ade41392284c065203b8ebc", "parameters": [ { "name": "strategy", "in": "path", "description": "Pricing strategy uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "discount": { "type": "number", "format": "float", "nullable": true }, "name": { "type": "string", "nullable": true }, "route_filters": { "type": "object", "nullable": true }, "demand_filters": { "type": "object", "nullable": true }, "class_settings": { "type": "object", "nullable": true }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "ends_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PricingStrategyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such strategy, or the token holder is not a member of its company" }, "422": { "description": "Refused: discount out of range, dates inverted, or filters the engine cannot use" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/pricing-strategies/{strategy}/state": { "patch": { "tags": [ "Public API v1" ], "description": "Pause, resume or end a strategy. One endpoint rather than the internal /pause, /resume and /end, because they are three transitions of one lifecycle and a tool should say what it wants rather than pick a verb from a state it has not read. `paused` is reversible; `ended` is PERMANENT, though it still keeps the record, so it is not the same as deleting. Asking for the state it is already in is answered rather than refused.\n\n**Requires:** scope `write:routes`, plus the company privilege `manage-pricing-strategies`.", "operationId": "519da96d4968a299ad1f8cabdc88d93f", "parameters": [ { "name": "strategy", "in": "path", "description": "Pricing strategy uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "state" ], "properties": { "state": { "type": "string", "enum": [ "active", "paused", "ended" ], "example": "paused" } }, "type": "object" } } } }, "responses": { "200": { "description": "Set", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1PricingStrategyResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks manage-pricing-strategies" }, "404": { "description": "No such strategy, or the token holder is not a member of its company" }, "422": { "description": "The strategy has already ended and cannot be paused or resumed" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/pricing-strategy-types": { "get": { "tags": [ "Public API v1" ], "description": "The filter kinds a pricing strategy can select by. `target` says whether a filter belongs in route_filters or demand_filters — putting one in the wrong half silently matches nothing.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "eb789ed1e45e1a2c1a548a8e49577ec9", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PricingStrategyTypeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/privileges": { "get": { "tags": [ "Public API v1" ], "description": "Every privilege the game defines. Reference data. Two jobs: building a role needs the slugs, and every 403 in v1 names a slug, so this is how a client turns a refusal into something it can show a person.\n\n**Requires:** scope `read:people` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "1942159bd980509c0b05d95be9877b1e", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1PrivilegeResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] } }, "/api/v1/quotes": { "post": { "tags": [ "Public API v1" ], "description": "Price a purchase and lock that price to you briefly. Returns a `quote` to send with the purchase itself, the price in pence, when it expires, and exactly where and with what fields it may be spent. Quoting needs the same scope and privilege as the purchase, because a price is information. Currently quotable: `agreement`, `field-service`.\n\n**Requires:** a scope matching the purchase being priced (`write:agreements` for an agreement, `write:fleet` for a field service), and the same company privilege that purchase needs. Quoting something is gated exactly like doing it.", "operationId": "4c0cc9ffec5d0d7f271242dd55163e8e", "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "for" ], "properties": { "for": { "description": "What is being priced.", "type": "string", "enum": [ "agreement", "field-service" ], "example": "agreement" }, "company": { "description": "For `agreement`: the signing company ICAO.", "type": "string", "example": "BLW" }, "airport": { "description": "For `agreement`: airport ICAO.", "type": "string", "example": "EGLL" }, "variant": { "description": "For `agreement`: variant slug from GET /agreement-variants.", "type": "string", "example": "large-domestic-slot" }, "aircraft": { "description": "For `field-service`: tail number.", "type": "string", "example": "G-ABCD" }, "check": { "description": "For `field-service`: c-check or d-check. A and B checks are free and need no quote.", "type": "string", "enum": [ "c-check", "d-check" ], "example": "c-check" } }, "type": "object" } } } }, "responses": { "200": { "description": "Quoted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Quote" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks the scope, or the role lacks the privilege, for the purchase being quoted" }, "404": { "description": "The token holder is not a member of the company involved" }, "422": { "description": "Not quotable in v1, or the details do not identify a purchase" } }, "security": [ { "bearerAuth": [] } ] } }, "/api/v1/rank-constraints/{constraint}": { "delete": { "tags": [ "Public API v1" ], "description": "Remove a constraint. The rank's aircraft mappings are recomputed, so what it may fly changes immediately.\n\n**Requires:** scope `write:roles`, plus the company privilege `update-ranks`.", "operationId": "7114c205b64b999ebe176c11d8de0aeb", "parameters": [ { "name": "constraint", "in": "path", "description": "Constraint uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks update-ranks" }, "404": { "description": "No such constraint, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change a constraint's parameters. MERGES into the existing data rather than replacing it, which differs from how PATCH /roles handles privileges. The type cannot be changed: delete and re-add instead.\n\n**Requires:** scope `write:roles`, plus the company privilege `update-ranks`.", "operationId": "854ee96dba44a5fb896768a8b3dbe9b2", "parameters": [ { "name": "constraint", "in": "path", "description": "Constraint uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "data" ], "properties": { "data": { "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RankConstraintResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks update-ranks" }, "404": { "description": "No such constraint, or the token holder is not a member of its company" }, "422": { "description": "Data the constraint type cannot accept, or an attempt to change `type`" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/ranks/{rank}": { "delete": { "tags": [ "Public API v1" ], "description": "Delete a rank. Refused rather than orphaning anyone if pilots currently hold it.\n\n**Requires:** scope `write:roles`, plus the company privilege `delete-ranks`.", "operationId": "81bfea4e530d30b9ce0fa682e97c6df7", "parameters": [ { "name": "rank", "in": "path", "description": "Rank uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks delete-ranks" }, "404": { "description": "No such rank, or the token holder is not a member of its company" }, "422": { "description": "Refused: pilots still hold this rank, or it is the owner rank" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Edit a rank. To change what it may fly, edit its constraints rather than the rank itself.\n\n**Requires:** scope `write:roles`, plus the company privilege `update-ranks`.", "operationId": "db41cc27d8aa6fbe6e1544c857c1e870", "parameters": [ { "name": "rank", "in": "path", "description": "Rank uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "allow_application_from": { "type": "integer", "nullable": true }, "auto_accept_from": { "type": "integer", "nullable": true }, "hourly_rate_pence": { "type": "integer", "nullable": true }, "pay_interval_hours": { "type": "integer", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyRankResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks update-ranks" }, "404": { "description": "No such rank, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/ranks/{rank}/aircraft": { "get": { "tags": [ "Public API v1" ], "description": "Which of the company's aircraft this rank may actually fly: the constraints EVALUATED rather than listed. Runs the same constraint engine the hire flow and job eligibility use, so the answer cannot drift from the game's.\n\n**Requires:** scope `read:people`, plus the company privilege `view-pilot-roster`.", "operationId": "2ce579446cc5e91fc56890dde128fdeb", "parameters": [ { "name": "rank", "in": "path", "description": "Rank uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1AircraftResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-pilot-roster" }, "404": { "description": "No such rank, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] } }, "/api/v1/ranks/{rank}/constraints": { "get": { "tags": [ "Public API v1" ], "description": "The rules limiting what this rank may fly. `data` passes through in the game's own shape because constraint types are open-ended and each reads it differently. For the evaluated answer rather than the rules, use /ranks/{rank}/aircraft.\n\n**Requires:** scope `read:people`, plus the company privilege `view-pilot-roster`.", "operationId": "7f60191731243ee34effb89563b4dd7d", "parameters": [ { "name": "rank", "in": "path", "description": "Rank uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RankConstraintResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-pilot-roster" }, "404": { "description": "No such rank, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Add a constraint limiting what this rank may fly. `data` is passed through in the game's own shape and validated against the type, because constraint types are open-ended.\n\n**Requires:** scope `write:roles`, plus the company privilege `update-ranks`.", "operationId": "956b359870e5302a4ff023df157ad12e", "parameters": [ { "name": "rank", "in": "path", "description": "Rank uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "type", "data" ], "properties": { "type": { "description": "Constraint type name, as listed by /api/v1/constraint-types.", "type": "string", "example": "aircraft-category" }, "data": { "description": "Parameters, read according to the type.", "type": "object" } }, "type": "object" } } } }, "responses": { "200": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RankConstraintResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks update-ranks" }, "404": { "description": "No such rank, or the token holder is not a member of its company" }, "422": { "description": "Unknown constraint type, or data the type cannot accept" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/regions": { "get": { "tags": [ "Public API v1" ], "description": "UN M49 sub-regions. `code` joins to `region` on GET /countries.\n\n**Requires:** scope `read:reference` and nothing else. No company membership or privilege applies to this endpoint.", "operationId": "1287fd49b057f7019a958a2d7bc52038", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RegionResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token does not carry the read:reference scope" } }, "security": [ { "bearerAuth": [ "read:reference" ] } ] } }, "/api/v1/roles/{role}": { "delete": { "tags": [ "Public API v1" ], "description": "Delete a role. Anyone holding it loses the privileges it granted.\n\n**Requires:** scope `write:roles`, plus the company privilege `manage-roles`.", "operationId": "1fa78b120756f3470679ea946d8b4310", "parameters": [ { "name": "role", "in": "path", "description": "Role uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks manage-roles" }, "404": { "description": "No such role, or the token holder is not a member of its company" }, "422": { "description": "Refused: the owner role cannot be deleted" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Rename a role or change what it permits. `privileges` REPLACES the list: omit it to leave privileges untouched, send an empty array to strip them all. Privileges are named by SLUG, the same slugs every 403 in v1 names. WARNING: this can widen what your own account may do.\n\n**Requires:** scope `write:roles`, plus the company privilege `manage-roles`.", "operationId": "65c52b5b5e51b65f88c0fdc90ea6ec2b", "parameters": [ { "name": "role", "in": "path", "description": "Role uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "name": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "colour": { "type": "string", "nullable": true }, "icon": { "type": "string", "nullable": true }, "privileges": { "description": "Slugs from GET /privileges. Replaces the existing list.", "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1CompanyRoleResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks manage-roles" }, "404": { "description": "No such role, or the token holder is not a member of its company" }, "422": { "description": "An unrecognised privilege slug. The whole request is refused rather than granting a subset." } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/roles/{role}/members": { "get": { "tags": [ "Public API v1" ], "description": "Who holds this role. ?holding=false inverts it and returns staff who do NOT, which is what a \"add someone to this role\" picker needs.\n\n**Requires:** scope `read:people`, plus the company privilege `view-role-details`.", "operationId": "f7dad964d4a14a919a341fb0ee175de5", "parameters": [ { "name": "role", "in": "path", "description": "Role uuid", "required": true, "schema": { "type": "string" } }, { "name": "holding", "in": "query", "description": "Set false for staff who do not hold the role.", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1StaffResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:people, or the role lacks view-role-details" }, "404": { "description": "No such role, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:people" ] } ] }, "post": { "tags": [ "Public API v1" ], "description": "Grant this role to people. A different privilege from editing the role itself: deciding what a role means and deciding who is in it are separate jobs.\n\n**Requires:** scope `write:roles`, plus the company privilege `manage-role-members`.", "operationId": "68b56a914a33e8c021724429580c58ba", "parameters": [ { "name": "role", "in": "path", "description": "Role uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "usernames" ], "properties": { "usernames": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Granted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RoleMembersChanged" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks manage-role-members" }, "404": { "description": "No such role or username" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Revoke this role from people.\n\n**Requires:** scope `write:roles`, plus the company privilege `manage-role-members`.", "operationId": "889cd01fdb072c84a842d96de54ba7b4", "parameters": [ { "name": "role", "in": "path", "description": "Role uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "required": [ "usernames" ], "properties": { "usernames": { "type": "array", "items": { "type": "string" } } }, "type": "object" } } } }, "responses": { "200": { "description": "Revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1RoleMembersChanged" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:roles, or the role lacks manage-role-members" }, "404": { "description": "No such role or username" } }, "security": [ { "bearerAuth": [ "write:roles" ] } ] } }, "/api/v1/routes/{route}": { "get": { "tags": [ "Public API v1" ], "description": "One route.\n\n**Requires:** scope `read:routes`, plus the company privilege `view-routes`.", "operationId": "504504f521938e4d2d132018bff2c6b8", "parameters": [ { "name": "route", "in": "path", "description": "Route UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks view-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] }, "delete": { "tags": [ "Public API v1" ], "description": "Close a route. Consequential beyond the route record: active jobs on it are RESET, which takes work off pilots who had accepted it. That is why closing carries its own privilege rather than sharing update-routes.\n\n**Requires:** scope `write:routes`, plus the company privilege `delete-routes`.", "operationId": "a7a6010ec54e0fda7d805b79a7933794", "parameters": [ { "name": "route", "in": "path", "description": "Route uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Closed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1Deleted" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks delete-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] }, "patch": { "tags": [ "Public API v1" ], "description": "Change a route's number, fares or minimums. This is the BROAD edit: for a single minimum use PATCH /routes/{uuid}/minimums, which exists so a bot does not have to read-modify-write a whole route and revert whatever a human changed in between.\n\n**Requires:** scope `write:routes`, plus the company privilege `update-routes`.", "operationId": "c6e62b9143390dc503f2e0bbc3f833b3", "parameters": [ { "name": "route", "in": "path", "description": "Route uuid", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "properties": { "number": { "type": "string", "nullable": true }, "fares": { "type": "object", "nullable": true } }, "type": "object" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks update-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" }, "422": { "description": "Refused: the number is taken" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/routes/{route}/disable": { "post": { "tags": [ "Public API v1" ], "description": "Close a route. Idempotent. NOTE: a disabled route stops accumulating demand — to park a route while it keeps building demand, raise a cabin minimum with PATCH /routes/{route}/minimums instead.\n\n**Requires:** scope `write:routes`, plus the company privilege `disable-routes`.", "operationId": "300e29a69bcdcce8c7f2a0c870f0fdf1", "parameters": [ { "name": "route", "in": "path", "description": "Route UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns the route", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks disable-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/routes/{route}/enable": { "post": { "tags": [ "Public API v1" ], "description": "Reopen a route the company had closed. Idempotent. Only affects the company's own switch, never FSCharter's.\n\n**Requires:** scope `write:routes`, plus the company privilege `enable-routes`.", "operationId": "b22bbcb1557779b72ba590e6f0a6b66c", "parameters": [ { "name": "route", "in": "path", "description": "Route UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success — returns the route", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks enable-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/routes/{route}/jobs": { "get": { "tags": [ "Public API v1" ], "description": "What this route has actually flown. Behind view-dispatch-plans as well as read:routes: seeing a route's fares is not the same as seeing its operational history.\n\n**Requires:** scope `read:routes`, plus the company privileges `view-routes`, `view-dispatch-plans`.", "operationId": "475355330b892b5f432c77a684431454", "parameters": [ { "name": "route", "in": "path", "description": "Route uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/V1JobResourceCollection" } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks read:routes, or the role lacks view-dispatch-plans" }, "404": { "description": "No such route, or the token holder is not a member of its company" } }, "security": [ { "bearerAuth": [ "read:routes" ] } ] } }, "/api/v1/routes/{route}/minimums": { "patch": { "tags": [ "Public API v1" ], "description": "Sets one or more cabin minimums, leaving every other route field untouched.\n\n**Requires:** scope `write:routes`, plus the company privilege `update-routes`.", "operationId": "9391d34dc6601cd572c3ccd789192fbd", "parameters": [ { "name": "route", "in": "path", "description": "Route UUID", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "properties": { "economy": { "type": "integer", "example": 10 }, "business": { "type": "integer", "example": 2 }, "first": { "type": "integer", "example": 300 }, "cargo": { "type": "number", "format": "float" }, "freight": { "type": "number", "format": "float" } }, "type": "object" } } } }, "responses": { "200": { "description": "Success — returns the updated route", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks update-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" }, "422": { "description": "No cabin supplied, or a value out of range" } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } }, "/api/v1/routes/{route}/refresh-demand": { "post": { "tags": [ "Public API v1" ], "description": "Ask the demand engine to recompute this route. REAL WORK, not a cheap read: it regenerates demand in Neo4j and the database, so it carries its own throttle for the same reason route-preview does. Behind update-routes rather than view-route-demand, because recomputing changes what every company sees on that pair.\n\n**Requires:** scope `write:routes`, plus the company privilege `update-routes`.", "operationId": "f0d3b1bb1521d4ab2683dfefe442891b", "parameters": [ { "name": "route", "in": "path", "description": "Route uuid", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Recomputed", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "$ref": "#/components/schemas/V1RouteResource" } } } } } }, "401": { "description": "Missing, invalid or revoked token" }, "403": { "description": "Token lacks write:routes, or the role lacks update-routes" }, "404": { "description": "No such route, or the token holder is not a member of its company" }, "429": { "description": "Throttled. Recomputing demand is expensive; six a minute." } }, "security": [ { "bearerAuth": [ "write:routes" ] } ] } } }, "components": { "schemas": { "V1AgreementCancellation": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nEchoes WHAT was cancelled rather than returning an empty success. The agreement\nis gone by the time this is read, so a client logging the response has no other\nway to record which slot at which airport it just gave up — and for a\ndestructive, irreversible action that log entry is the thing someone will want\nlater.", "type": "string", "example": "success" }, "data": { "required": [ "cancelled", "company_icao" ], "properties": { "cancelled": { "type": "boolean", "example": true }, "company_icao": { "type": "string", "example": "BLW" }, "airport_icao": { "type": "string", "example": "EGLL", "nullable": true }, "variant": { "description": "The variant slug, so a client can sign the same kind again.", "type": "string", "example": "large-domestic-slot", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1AgreementResource": { "required": [ "uuid", "airport_icao" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nAn agreement is a company's standing arrangement at an airport, and what it\nactually buys you is CAPACITY: parking slots, gates, cargo handling. So the\nuseful part of this response is `capacity`, not the agreement's name.\n\n`capacity` reports used, total and free per capability. `free` is computed\nrather than left to the client, because \"can I park another plane here?\" is\nthe question every tool asks and a subtraction is a place to get it wrong. It\nis derived, never authoritative: attempting the move is still what decides.", "type": "string", "example": "b81f5a10-3c2d-4e5f-8a9b-0c1d2e3f4a5b" }, "name": { "type": "string", "example": "EGLL Stand 12", "nullable": true }, "airport_icao": { "type": "string", "example": "EGLL", "nullable": true }, "airport_name": { "type": "string", "example": "London Heathrow", "nullable": true }, "variant": { "description": "Which kind of agreement this is. `slug` is the stable identifier; POST /companies/{icao}/agreements takes it.", "properties": { "uuid": { "type": "string" }, "slug": { "type": "string", "example": "parking-slot-small" }, "name": { "type": "string", "example": "Small Parking Slot" }, "type": { "type": "string", "example": "Parking" }, "cancellable": { "type": "boolean", "example": true }, "minimum_term_cycles": { "type": "integer", "example": 4, "nullable": true } }, "type": "object", "nullable": true }, "capacity": { "description": "What this agreement provides and how much of it is in use.", "type": "array", "items": { "properties": { "capability": { "type": "string", "example": "aircraft-parking" }, "name": { "type": "string", "example": "Aircraft Parking" }, "unit": { "type": "string", "example": "slots", "nullable": true }, "used": { "type": "number", "format": "float", "example": 1 }, "total": { "type": "number", "format": "float", "example": 2 }, "free": { "description": "total - used, never negative.", "type": "number", "format": "float", "example": 1 }, "usage_uuid": { "description": "Identifies this slot for POST /aircraft/{registration}/vacate-slot.", "type": "string" } }, "type": "object" } } }, "type": "object" }, "V1AgreementResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AgreementResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" }, "V1AgreementVariantResource": { "required": [ "uuid", "slug", "name" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\n`slug` is the identifier POST /companies/{icao}/agreements wants, and it is the\none to store: variant names are display copy and get rewritten, slugs do not.\n\nThe airport-size and operations-centre requirements are here so a client can\ntell a user WHY a variant is unavailable at their airport, rather than sending\na request that fails and reporting a bare error.", "type": "string" }, "slug": { "description": "Stable identifier. Use this, not the name.", "type": "string", "example": "parking-slot-small" }, "name": { "type": "string", "example": "Small Parking Slot" }, "type": { "type": "string", "example": "Parking", "nullable": true }, "cancellable": { "type": "boolean", "example": true }, "minimum_term_cycles": { "type": "integer", "example": 4, "nullable": true }, "requires": { "description": "Conditions the airport must meet. Check these against GET /airports/{icao} before signing, to explain a refusal in advance rather than reporting a bare error.", "properties": { "minimum_airport_size": { "description": "Compare with `size` on GET /airports/{icao}, or with `size_rank` for an ordering.", "type": "string", "enum": [ "heliport", "balloonport", "small_airport", "medium_airport", "large_airport" ], "example": "medium_airport", "nullable": true }, "maximum_airport_size": { "type": "string", "example": "large_airport", "nullable": true }, "minimum_operations_centre_size": { "type": "string", "example": "large", "nullable": true }, "operations_centre_type": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1AgreementVariantResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AgreementVariantResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 24 } }, "type": "object" } }, "type": "object" }, "V1AircraftCategoryResource": { "required": [ "code", "name" ], "properties": { "code": { "description": "Stable identifier, and what the hours breakdown on a pilot profile is keyed by.", "type": "string", "example": "SRA" }, "name": { "type": "string", "example": "Short Range Airliner" } }, "type": "object" }, "V1AircraftCategoryResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftCategoryResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 7 } }, "type": "object" } }, "type": "object" }, "V1AircraftImage": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "registration" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "image_url": { "description": "Null after a DELETE.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1AircraftRankResource": { "required": [ "uuid", "name", "eligible", "can_fly_aircraft" ], "properties": { "uuid": { "description": "Pass as `rank_uuid` when hiring.", "type": "string" }, "name": { "type": "string", "example": "First Officer" }, "can_fly_aircraft": { "description": "The rank's constraints permit this particular aircraft.", "type": "boolean", "example": true }, "eligible": { "description": "You may hold this rank, by global rank, progression, or because you already do.", "type": "boolean", "example": true }, "auto_approve": { "description": "Applying would be accepted immediately rather than waiting for a human.", "type": "boolean", "example": false }, "is_current_rank": { "description": "You hold this rank right now.", "type": "boolean", "example": false }, "is_pending_rank": { "description": "You have applied and are waiting.", "type": "boolean", "example": false } }, "type": "object" }, "V1AircraftRankResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated, like the service schedule. A company defines a handful of\nranks and that number is set by the company, not by activity, so paging them\nwould make clients write a loop that runs once.\n\nBecause there is no paginator, this deliberately does NOT override toArray():\nthe parent maps each row through AircraftRankResource, which is what is\nwanted. See AircraftServiceScheduleResourceCollection for the full note.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftRankResource" } } }, "type": "object" }, "V1AircraftResource": { "required": [ "registration" ], "properties": { "registration": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nIdentified by `registration` (the tail number), because that is what a pilot\nor an ops tool actually calls an aircraft. The aircraft table has no uuid, and\nthe internal `id` is deliberately absent.\n\n`location` carries the current airport, `home_base` the registration airport.\nBoth are objects rather than bare idents so an added field later (name,\ncountry) does not need a new key.", "type": "string", "example": "G-ABCD" }, "type": { "properties": { "icao": { "type": "string", "example": "C172" }, "manufacturer": { "type": "string", "example": "Cessna" }, "model": { "type": "string", "example": "172 Skyhawk" } }, "type": "object", "nullable": true }, "location": { "description": "Where the aircraft is now. Null while airborne between airports.", "properties": { "icao": { "type": "string", "example": "EGLL" } }, "type": "object", "nullable": true }, "home_base": { "properties": { "icao": { "type": "string", "example": "EGKK" } }, "type": "object", "nullable": true }, "seats": { "properties": { "economy": { "type": "integer", "example": 4 }, "business": { "type": "integer", "example": 0 }, "first": { "type": "integer", "example": 0 } }, "type": "object" }, "cargo_capacity_kg": { "type": "integer", "example": 500, "nullable": true }, "flight_hours": { "type": "number", "format": "float", "example": 412.5 }, "flight_cycles": { "type": "integer", "example": 180 }, "fuel": { "type": "number", "format": "float", "example": 120.4, "nullable": true }, "available_for_hire": { "type": "boolean", "example": false }, "frozen": { "type": "boolean", "example": false }, "on_job": { "type": "boolean", "example": true }, "current_job": { "description": "The job this aircraft is currently flying, or null. Ask GET /api/v1/jobs/{uuid} for the detail.", "properties": { "uuid": { "type": "string", "example": "9c1f8f6e-4f0a-4a4a-9c7e-0f2b1d3e4a5b" }, "number": { "type": "integer", "example": 1234, "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "V1AircraftResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 12 } }, "type": "object" } }, "type": "object" }, "V1AircraftSale": { "required": [ "status", "data" ], "properties": { "status": { "description": "Withdrawing a listing answers with a DIFFERENT shape, and it needs its own\nschema rather than reusing the one above.\n\nThe first version of this documented DELETE as returning V1AircraftSale, whose\n`sold_to` is required. Nothing has been sold when you take a listing down, so\nthe action rightly did not send one, and the spec and the code disagreed. A\ngenerated client would have refused to parse a perfectly good response. The\nresponse-validating test harness caught it.", "type": "string", "example": "success" }, "data": { "required": [ "registration", "sold_to" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "sold_to": { "description": "`broker` is done and irreversible. `classifieds` is listed and still cancellable.", "type": "string", "enum": [ "broker", "classifieds" ], "example": "classifieds" }, "listing": { "description": "The listing uuid, for a classifieds sale. Null for a broker sale.", "type": "string", "nullable": true }, "proceeds_pence": { "description": "What the broker paid. Null for a listing, because nothing has been paid yet.", "type": "integer", "example": 3900000, "nullable": true } }, "type": "object" } }, "type": "object" }, "V1AircraftServiceScheduleResource": { "required": [ "check", "overdue" ], "properties": { "check": { "description": "Service type slug, e.g. a-check.", "type": "string", "example": "a-check" }, "name": { "type": "string", "example": "A Check" }, "privilege": { "description": "The company privilege needed to book this check. Read it rather than guessing from the slug.", "type": "string", "example": "perform-a-checks", "nullable": true }, "interval_hours": { "type": "integer", "example": 500, "nullable": true }, "hours_since_last_service": { "type": "number", "format": "float", "example": 431.2 }, "hours_remaining": { "type": "number", "format": "float", "example": 68.8 }, "hours_overdue": { "description": "Zero unless overdue.", "type": "number", "format": "float", "example": 0 }, "progress": { "description": "Fraction of the interval used. Can exceed 1 when overdue.", "type": "number", "format": "float", "example": 0.86 }, "due_soon": { "type": "boolean", "example": true }, "overdue": { "type": "boolean", "example": false }, "automatic": { "description": "Whether FSCharter books this check for you.", "type": "boolean", "example": false } }, "type": "object" }, "V1AircraftServiceScheduleResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated, unlike every other collection in v1. An aircraft is on a\nhandful of checks (A, B, C, D) and that number is fixed by the game, not by\nhow much the player has done. Paging four rows would make clients write a\nloop that can only ever run once.\n\nBecause there is no paginator, this deliberately does NOT override toArray()\nthe way the paginated collections do: the parent implementation maps each row\nthrough AircraftServiceScheduleResource, which is exactly what is wanted here.\nReturning `$this->resource->toArray()` (right for a paginator) would hand back\nraw model attributes and bypass the resource entirely.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftServiceScheduleResource" } } }, "type": "object" }, "V1AircraftServiceTypeResource": { "required": [ "slug", "name" ], "properties": { "slug": { "description": "What the maintenance endpoints name.", "type": "string", "example": "c-check" }, "name": { "type": "string", "example": "C Check" }, "description": { "type": "string", "nullable": true }, "interval_hours": { "description": "Flight hours between checks of this kind. Null for a job that is not on a schedule, like a seat reconfiguration.", "type": "integer", "nullable": true }, "restricted": { "description": "True when ordering it needs a privilege beyond the usual maintenance one.", "type": "boolean" } }, "type": "object" }, "V1AircraftServiceTypeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftServiceTypeResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" }, "V1AircraftTypeResource": { "required": [ "slug", "icao_code" ], "properties": { "slug": { "description": "Stable identifier. Use this, not the ICAO code, which is not unique across variants.", "type": "string", "example": "boeing-737-800" }, "icao_code": { "description": "Not unique: variants of one airframe share it.", "type": "string", "example": "B738" }, "manufacturer": { "type": "string", "example": "Boeing", "nullable": true }, "model": { "type": "string", "example": "737", "nullable": true }, "variant": { "type": "string", "example": "-800", "nullable": true }, "category": { "description": "Category code, matching GET /aircraft-categories and the hours breakdown on a pilot profile.", "type": "string", "example": "SRA", "nullable": true }, "price": { "description": "List price in pence. What you actually pay is quoted.", "type": "integer", "nullable": true }, "max_pax_seats": { "type": "integer", "example": 189, "nullable": true }, "weights": { "description": "All in the game's own unit. These only mean anything against each other.", "properties": { "empty": { "type": "number", "format": "float", "nullable": true }, "max_takeoff": { "description": "MTOW. This is what the AOC level caps.", "type": "number", "format": "float", "nullable": true }, "max_landing": { "type": "number", "format": "float", "nullable": true }, "max_zero_fuel": { "type": "number", "format": "float", "nullable": true }, "max_payload": { "description": "Generated by the game from MZFW and empty weight.", "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "performance": { "properties": { "range": { "type": "number", "format": "float", "nullable": true }, "cruise_speed": { "type": "number", "format": "float", "nullable": true }, "max_speed": { "type": "number", "format": "float", "nullable": true }, "ceiling": { "type": "number", "format": "float", "nullable": true }, "fuel_capacity": { "type": "number", "format": "float", "nullable": true }, "fuel_burn": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "dimensions": { "description": "Airframe size, plus the cargo hold. `footprint` is generated by the game from span and length and is what a parking slot is measured against.", "properties": { "length": { "type": "number", "format": "float", "nullable": true }, "height": { "type": "number", "format": "float", "nullable": true }, "wing_span": { "type": "number", "format": "float", "nullable": true }, "footprint": { "type": "number", "format": "float", "nullable": true }, "hold_width_cm": { "type": "integer", "nullable": true }, "hold_height_cm": { "type": "integer", "nullable": true }, "hold_length_cm": { "type": "integer", "nullable": true }, "hold_volume_m3": { "type": "number", "format": "float", "nullable": true } }, "type": "object" }, "image": { "description": "Null when we hold no image. When present, the attribution travels with it: publishing the URL without the licence and author would breach the terms we hold it under.", "properties": { "url": { "type": "string", "nullable": true }, "licence": { "type": "string", "nullable": true }, "author": { "type": "string", "nullable": true }, "source": { "type": "string", "nullable": true } }, "type": "object", "nullable": true } }, "type": "object" }, "V1AircraftTypeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated: 232 types, and the payload per row is not small.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1AircraftTypeResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 5 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 232 } }, "type": "object" } }, "type": "object" }, "V1AirportResource": { "required": [ "icao", "name" ], "properties": { "icao": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nShared reference data: the same answer for every token, describing the world\nrather than anyone's company. Nothing here reveals who operates at the airport,\nwhich is why it needs no privilege.\n\n`size` and `size_rank` are both present. `size` is the raw name, which is what\nvariant requirements are expressed in and so what you compare for equality.\n`size_rank` is the game's own ordering of those names, which is what you need\nfor \"is this airport big enough?\" — a comparison a client cannot make from the\nstrings, and would otherwise have to hardcode our enum to make.\n\n`runways` breaks down by surface because that is what decides whether an\naircraft can use the airport at all. A float plane and an airliner read\ndifferent keys.", "type": "string", "example": "EGLL" }, "iata": { "type": "string", "example": "LHR", "nullable": true }, "name": { "type": "string", "example": "London Heathrow Airport" }, "country": { "description": "ISO 3166-1 alpha-2.", "type": "string", "example": "GB", "nullable": true }, "country_name": { "type": "string", "example": "United Kingdom", "nullable": true }, "size": { "description": "Raw size name. Compare for equality against a variant's requires.minimum_airport_size.", "type": "string", "enum": [ "heliport", "balloonport", "small_airport", "medium_airport", "large_airport" ], "example": "large_airport", "nullable": true }, "size_rank": { "description": "The game's ordering of those names: 1 small or special, 2 medium, 3 large. Use for \"big enough?\" comparisons rather than hardcoding the list.", "type": "integer", "example": 3, "nullable": true }, "elevation_ft": { "type": "integer", "example": 83, "nullable": true }, "location": { "properties": { "latitude": { "type": "number", "format": "float", "example": 51.4706 }, "longitude": { "type": "number", "format": "float", "example": -0.4619 } }, "type": "object", "nullable": true }, "runways": { "description": "Counts by surface. Which key matters depends on the aircraft.", "properties": { "total": { "type": "integer", "example": 2 }, "hard": { "type": "integer", "example": 2 }, "soft": { "type": "integer", "example": 0 }, "water": { "type": "integer", "example": 0 }, "helipad": { "type": "integer", "example": 0 } }, "type": "object" }, "ramps": { "description": "Public parking positions.", "type": "integer", "example": 40, "nullable": true } }, "type": "object" }, "V1AocLevel": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "icao", "aoc_level" ], "properties": { "icao": { "type": "string", "example": "BLW" }, "aoc_level": { "description": "Caps what the company may fly, by aircraft maximum takeoff weight. Checked when buying an aircraft and when receiving one by transfer.", "type": "string", "enum": [ "small", "medium", "large" ], "example": "medium" } }, "type": "object" } }, "type": "object" }, "V1BuildingResource": { "required": [ "uuid", "airport_icao" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nShaped to match AgreementResource on purpose. Buildings and agreements are\ndifferent things in the game but the same thing to a tool: both are a\ncontainer at an airport providing capacity, and both answer \"have I got room\nhere?\". Giving them the same `capacity` shape means one function handles both.", "type": "string" }, "name": { "type": "string", "example": "EGCC Hangar 1", "nullable": true }, "description": { "type": "string", "nullable": true }, "airport_icao": { "type": "string", "example": "EGCC", "nullable": true }, "airport_name": { "type": "string", "nullable": true }, "variant": { "properties": { "uuid": { "type": "string" }, "slug": { "type": "string", "example": "hangar-small" }, "name": { "type": "string", "example": "Small Hangar" }, "type": { "type": "string", "example": "Hangar", "nullable": true } }, "type": "object", "nullable": true }, "capacity": { "description": "Same shape as an agreement's capacity, so one client function reads both.", "type": "array", "items": { "properties": { "capability": { "type": "string", "example": "aircraft-storage" }, "name": { "type": "string" }, "unit": { "type": "string", "nullable": true }, "used": { "type": "number", "format": "float" }, "total": { "type": "number", "format": "float" }, "free": { "type": "number", "format": "float" }, "usage_uuid": { "type": "string" } }, "type": "object" } } }, "type": "object" }, "V1BuildingResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1BuildingResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" }, "V1BuildingVariantResource": { "required": [ "slug", "name" ], "properties": { "slug": { "description": "Pass as `variant` when buying.", "type": "string", "example": "large-hangar" }, "name": { "type": "string", "example": "Large Hangar" }, "type": { "description": "What the building does: hangar, service centre and so on.", "type": "string", "example": "hangar", "nullable": true }, "requires": { "description": "What you must already hold to buy this. Check against your operations centres before offering it to a user.", "properties": { "minimum_operations_centre_size": { "type": "string", "example": "medium", "nullable": true }, "operations_centre_type": { "type": "string", "nullable": true }, "minimum_airport_size": { "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1BuildingVariantResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated, matching AgreementVariantResourceCollection. This is a fixed\ncatalogue set by the game, not a list that grows with what a player does, so\npaging it would make clients write a loop that runs once.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1BuildingVariantResource" } } }, "type": "object" }, "V1CapabilityTypeResource": { "required": [ "slug", "name" ], "properties": { "slug": { "description": "What GET /companies/{icao}/capabilities/{slug} takes.", "type": "string", "example": "store-aircraft" }, "name": { "type": "string", "example": "Store Aircraft" }, "description": { "type": "string", "nullable": true }, "unit": { "description": "What one unit of it is.", "type": "string", "example": "aircraft", "nullable": true }, "value_description": { "description": "How to read the number, in words.", "type": "string", "nullable": true }, "holds_items": { "description": "True when the capability holds things (aircraft in a hangar) rather than being a rate or an allowance.", "type": "boolean" }, "is_service": { "description": "True when it performs work (a maintenance check) rather than providing space.", "type": "boolean" } }, "type": "object" }, "V1CapabilityTypeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CapabilityTypeResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 10 } }, "type": "object" } }, "type": "object" }, "V1ClassifiedListingResource": { "required": [ "uuid", "price_pence" ], "properties": { "uuid": { "description": "Pass to POST /classifieds/{uuid}/purchase.", "type": "string" }, "price_pence": { "type": "integer", "example": 4250000 }, "original_price_pence": { "description": "Only present when the seller has reduced the price since listing.", "type": "integer", "example": 5000000, "nullable": true }, "description": { "description": "Free text written by the seller.", "type": "string", "nullable": true }, "seller_icao": { "description": "Null when the broker is selling.", "type": "string", "example": "BLW", "nullable": true }, "seller_name": { "type": "string", "nullable": true }, "aircraft": { "description": "Embedded, because GET /aircraft/{registration} would refuse: it belongs to someone else.", "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "type_icao": { "type": "string", "example": "C172", "nullable": true }, "manufacturer": { "type": "string", "example": "Cessna", "nullable": true }, "model": { "type": "string", "example": "172 Skyhawk", "nullable": true }, "location_icao": { "description": "Where it stands, and therefore where you collect it.", "type": "string", "example": "EGCC", "nullable": true }, "flight_hours": { "type": "number", "format": "float", "example": 412.5 }, "flight_cycles": { "type": "integer", "example": 180 }, "seats": { "properties": { "economy": { "type": "integer", "example": 4 }, "business": { "type": "integer", "example": 0 }, "first": { "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object", "nullable": true }, "listed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1ClassifiedListingResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1ClassifiedListingResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 6 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 284 } }, "type": "object" } }, "type": "object" }, "V1CommodityResource": { "required": [ "slug", "name" ], "properties": { "slug": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nSomething the game flies for money. Covers passengers (economy through VIP)\nas well as cargo and freight, which is why `is_cargo` and `is_freight` are\nboth here: a passenger is neither.\n\nThe demand-engine internals on this table stay internal, all of them:\n`weighting`, `price_divisor`, `geo_score_field`, the charter-bonus decay and\nthe capacity-penalty curve. Those are the pricing model, they get retuned, and\npublishing them in a frozen contract would both leak how the economy works and\nstop us changing it.", "type": "string", "example": "passenger-economy" }, "name": { "type": "string", "example": "Economy Passenger" }, "unit": { "description": "What one of it is: a passenger, a bag, a pallet.", "type": "string", "nullable": true }, "mass_per_unit_g": { "description": "Grams per unit, which is what payload maths needs.", "type": "integer", "nullable": true }, "is_cargo": { "type": "boolean" }, "is_freight": { "type": "boolean" }, "charter_only": { "description": "Only ever appears on charter work, never scheduled demand.", "type": "boolean" } }, "type": "object" }, "V1CommodityResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CommodityResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 37 } }, "type": "object" } }, "type": "object" }, "V1CompanyActivityResource": { "required": [ "uuid", "type", "title" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne entry in the company's activity log. The internal record also carries\n`link`, `link_text` and `link_icon` fields, but those are the website's own\ndeep-links and Font Awesome icon names — publishing them would publish our\nUI, not the company's activity. There is no actor field: the internal record\nbakes whoever did it into the prose `title` (e.g. \"SirLoin joined as staff\").", "type": "string" }, "type": { "type": "string", "example": "new-staff" }, "title": { "type": "string", "example": "SirLoin joined as staff" }, "description": { "type": "string", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1CompanyActivityResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CompanyActivityResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 12 } }, "type": "object" } }, "type": "object" }, "V1CompanyDirectoryResource": { "required": [ "icao", "name" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne entry in the public company directory. Readable by any token, staff or\nnot — this is the same list the website shows to logged-out visitors.", "type": "string" }, "icao": { "type": "string", "example": "FSC" }, "name": { "type": "string", "example": "FSCharter Air" }, "logo": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "aircraft_count": { "type": "integer" }, "routes_count": { "type": "integer" }, "pilots_count": { "type": "integer" }, "created_at": { "type": "string", "format": "date-time", "nullable": true }, "latest_flight_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1CompanyDirectoryResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CompanyDirectoryResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 50 } }, "type": "object" } }, "type": "object" }, "V1CompanyExists": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass — the internal action already returns a plain array.", "type": "string", "example": "success" }, "data": { "required": [ "exists" ], "properties": { "exists": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "V1CompanyFinancesResource": { "required": [ "status", "data" ], "properties": { "status": { "description": "PUBLIC CONTRACT (v1).\n\nThe unit is in the field name. FSCharter stores money in pence, and a public\nAPI field called `balance` would be guessed as pounds by half the people who\nused it. `balance_pence` cannot be misread.", "type": "string", "example": "success" }, "data": { "required": [ "company_icao", "balance_pence" ], "properties": { "company_icao": { "type": "string", "example": "BLW" }, "account_number": { "type": "string", "example": "12345678" }, "balance_pence": { "type": "integer", "example": 3000000000 }, "transferable_pence": { "description": "How much may be MOVED right now, which is not the balance: outstanding loan obligations are reserved and the figure is bounded by the month's profit. Check this before queueing a payment rather than attempting one and reading the refusal.", "type": "integer", "example": 250000000 }, "transfer_limit": { "description": "Why transferable_pence is that number, so a client can explain a refusal instead of only reporting it.", "properties": { "basis": { "description": "Which limit binds.", "type": "string", "enum": [ "balance", "profit" ], "example": "balance" }, "outstanding_obligation_pence": { "description": "Loan principal plus remaining scheduled interest, reserved out of the balance.", "type": "integer", "example": 50000000 }, "monthly_profit_pence": { "type": "integer", "example": 12000000 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1CompanyPrivileges": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nThree lists rather than one, because \"can I do this?\" has two different\nnegative answers and a client needs to tell them apart. `privileges` is what\nthe player's role carries, `token_scopes` is what this token was granted, and\n`effective` is the intersection — the only one that predicts whether a request\nwill succeed. A tool that gets a 403 can look here and say either \"ask your\ncompany admin for this privilege\" or \"this token was not created with that\nscope, make a new one\", which are completely different instructions to give\nsomeone.", "type": "string", "example": "success" }, "data": { "required": [ "company_icao", "privileges", "token_scopes", "effective" ], "properties": { "company_icao": { "type": "string", "example": "BLW" }, "privileges": { "description": "Everything the player's role carries here, ignoring the token.", "type": "array", "items": { "type": "string", "example": "view-aircraft" } }, "token_scopes": { "description": "The scopes this token holds.", "type": "array", "items": { "type": "string", "example": "read:fleet" } }, "effective": { "description": "Role AND scope. What this token can actually reach right now.", "type": "array", "items": { "type": "string", "example": "view-aircraft" } } }, "type": "object" } }, "type": "object" }, "V1CompanyRankResource": { "required": [ "uuid", "name" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\n`uuid` is the value POST /api/v1/jobs/{uuid}/accept wants for `rank`.\n\n`hourly_rate_pence` is what the company pays a pilot flying under this rank.\nIt is on the rank rather than hidden behind the finance privilege because a\npilot deciding whether to accept a job needs to know what it pays, and the\nrank card in the app shows it to anyone who can see the roster.", "type": "string", "example": "5f1c9a72-8b6d-4e3a-9c1f-7a2b3c4d5e6f" }, "name": { "type": "string", "example": "First Officer" }, "description": { "type": "string", "nullable": true }, "owner_rank": { "description": "The rank a company owner flies under.", "type": "boolean", "example": false }, "your_rank": { "description": "Whether the token holder currently flies under this rank.", "type": "boolean", "example": true }, "hourly_rate_pence": { "type": "integer", "example": 4500, "nullable": true }, "pay_interval_hours": { "type": "integer", "example": 1, "nullable": true } }, "type": "object" }, "V1CompanyRankResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated: this list is bounded by the game rather than by activity, so\npaging it would make clients write a loop that only ever runs once. See\nAircraftServiceScheduleResourceCollection for why toArray() is left alone.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CompanyRankResource" } } }, "type": "object" }, "V1CompanyResource": { "required": [ "icao", "name" ], "properties": { "icao": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; they must not be renamed, retyped\nor removed for the life of v1.\n\nIdentified by `icao`, which is how every other v1 route addresses a company,\nplus `uuid` for anything that wants an opaque key. The internal auto-increment\n`id` is deliberately absent: exposing it would leak row counts and tie clients\nto a column we might one day stop using as the primary key.\n\nNo money here. Balances live at /companies/{icao}/finances behind\nread:finance and view-finances.", "type": "string", "example": "BLW" }, "uuid": { "type": "string", "example": "1dd1ffd2-1a46-4b09-9dba-289948ec7466" }, "name": { "type": "string", "example": "Bluestar Airways" }, "description": { "type": "string", "nullable": true }, "logo": { "type": "string", "nullable": true }, "aoc_level": { "type": "integer", "example": 2, "nullable": true }, "accepts_asset_transfers": { "type": "boolean", "example": true }, "created_at": { "type": "string", "example": "2026-01-04T09:00:00.000000Z", "nullable": true } }, "type": "object" }, "V1CompanyResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CompanyResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1CompanyRoleResource": { "required": [ "uuid", "name" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne role, and what it permits.\n\n`privileges` is a list of SLUGS rather than objects, and the slug is the\ncontract. Names get rewritten for the website's own copy; slugs do not, and it\nis slugs that PATCH /roles/{uuid} takes and that every 403 message in v1 names.\nA client that reads a refusal saying \"does not carry the 'transfer-funds'\nprivilege\" can find the role granting it by matching on this list.\n\n`member_count` rather than the members themselves. A role list is often long\nand the members are a separate endpoint; embedding them would make listing\nroles quadratic in staff.", "type": "string" }, "name": { "type": "string", "example": "Ops Manager" }, "description": { "type": "string", "nullable": true }, "privileges": { "description": "Privilege SLUGS, which is what the 403 messages name and what PATCH takes. Stable across copy changes in a way names are not.", "type": "array", "items": { "type": "string" }, "example": [ "view-aircraft", "create-dispatch-plans" ] }, "member_count": { "description": "How many people hold it. The members themselves are GET /roles/{uuid}/members.", "type": "integer", "example": 3 } }, "type": "object" }, "V1CompanyRoleResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CompanyRoleResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" }, "V1ConstraintTypeResource": { "required": [ "name" ], "properties": { "name": { "description": "What POST rank constraints names.", "type": "string", "example": "in-any-company-aircraft" }, "description": { "type": "string", "nullable": true }, "group": { "description": "What the website groups it under.", "type": "string", "nullable": true }, "pilot_description_template": { "description": "The sentence shown to a pilot, placeholders included.", "type": "string", "nullable": true }, "is_aircraft_definition": { "description": "True when the constraint describes which aircraft qualify, rather than a property of the flight.", "type": "boolean" } }, "type": "object" }, "V1ConstraintTypeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1ConstraintTypeResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 5 } }, "type": "object" } }, "type": "object" }, "V1CountryResource": { "required": [ "code", "name" ], "properties": { "code": { "description": "ISO alpha-2. What every v1 endpoint taking a country expects.", "type": "string", "example": "GB" }, "alpha_three": { "type": "string", "example": "GBR", "nullable": true }, "name": { "type": "string", "example": "United Kingdom" }, "continent": { "type": "string", "nullable": true }, "region": { "description": "UN M49 sub-region code. Matches `code` on GET /regions — both are integers, so the join needs no coercion.", "type": "integer", "example": 154, "nullable": true }, "currency_code": { "type": "string", "example": "GBP", "nullable": true } }, "type": "object" }, "V1CountryResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1CountryResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 246 } }, "type": "object" } }, "type": "object" }, "V1CurrentMonthProfit": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass. Profit = (job + fuel income) minus every outgoing payment this\ncalendar month, in pence.", "type": "string", "example": "success" }, "data": { "required": [ "profit", "income", "expenses", "days_until_end_of_month" ], "properties": { "profit": { "description": "Pence. Can be negative.", "type": "integer" }, "income": { "type": "integer" }, "expenses": { "type": "integer" }, "days_until_end_of_month": { "type": "integer" } }, "type": "object" } }, "type": "object" }, "V1Deleted": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "uuid", "deleted" ], "properties": { "uuid": { "description": "The thing that was deleted. It no longer exists.", "type": "string" }, "deleted": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "V1DemandReleased": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "released", "uuids" ], "properties": { "released": { "description": "How many pieces of demand were handed to the pool. Zero is a normal answer.", "type": "integer", "example": 12 }, "uuids": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "V1DispatchPlanResource": { "required": [ "uuid", "released" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA dispatch plan: the draft a company builds jobs inside before releasing them\nto its pilots.\n\n`released` is the field that decides what a client may do next, and it is\npublished as a boolean alongside the timestamp because it is a state rather\nthan a date. While false the plan is a draft: jobs and legs can be added and\nremoved, and no pilot can see any of it. Once true the work is live and\nediting it means resetting jobs pilots may already have accepted.\n\n`expires_at` matters more than it looks. A draft left alone is cleaned up, so a\ntool building a plan across several requests has a deadline.", "type": "string" }, "name": { "type": "string", "nullable": true }, "company_icao": { "type": "string", "example": "BLW", "nullable": true }, "released": { "description": "False means a draft: editable, and invisible to pilots. True means the work is live.", "type": "boolean", "example": false }, "released_at": { "type": "string", "format": "date-time", "nullable": true }, "status": { "type": "string", "nullable": true }, "jobs": { "description": "The jobs built inside this plan, by uuid and number. Full detail is GET /jobs/{uuid}.", "type": "array", "items": { "properties": { "uuid": { "type": "string" }, "number": { "type": "integer", "nullable": true } }, "type": "object" } }, "expires_at": { "description": "A draft left alone is cleaned up. Build within this.", "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "V1DispatchPlanResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1DispatchPlanResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 8 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 372 } }, "type": "object" } }, "type": "object" }, "V1EstateSale": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nThe outcome of selling a building or an operations centre. One schema for both,\nbecause the game refunds them the same way.\n\n`refund_percent` and `days_owned` are published alongside the money for a\nreason. You do NOT get the purchase price back: the refund is a percentage that\ndecays with how long you have owned the thing. Returning only\n`proceeds_pence` would leave every client showing a number smaller than the\nuser expected with no way to explain it, and the obvious guess (\"we were\ncharged a fee\") would be wrong.", "type": "string", "example": "success" }, "data": { "required": [ "uuid", "sold", "proceeds_pence" ], "properties": { "uuid": { "description": "The thing that was sold. It no longer exists.", "type": "string" }, "sold": { "type": "boolean", "example": true }, "proceeds_pence": { "description": "What was paid into the company account.", "type": "integer", "example": 1875000 }, "refund_percent": { "description": "The proportion of the original price refunded. Decays with age, which is why the proceeds are lower than the purchase price.", "type": "number", "format": "float", "example": 62.5 }, "days_owned": { "type": "integer", "example": 340 } }, "type": "object" } }, "type": "object" }, "V1FerryEstimate": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nWhat ferrying an aircraft somewhere empty would cost.\n\nEvery money field is named `_estimate_pence` rather than `_pence`, and that is\nnot padding. This is NOT a quote: nothing is locked and nothing is reserved.\nFuel prices and airport fees move with the economy, so the figure can differ\nby the time the ferry job is created. Naming them the way the priced endpoints\nare named would invite a client to show one of these to a person as a price.", "type": "string", "example": "success" }, "data": { "required": [ "registration", "to", "total_estimate_pence" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "from": { "description": "Where the aircraft is now. Null while airborne.", "type": "string", "example": "EGCC", "nullable": true }, "to": { "type": "string", "example": "EGLL" }, "distance_nm": { "type": "number", "format": "float", "example": 152.4 }, "fuel_estimate_pence": { "description": "The fuel burned over the distance plus 20% for departure and arrival routes, at the aircraft's own average burn where it has flown enough to have one, otherwise at the type's book burn at cruise speed.", "type": "integer", "example": 84000 }, "atc_estimate_pence": { "type": "integer", "example": 12000 }, "landing_estimate_pence": { "description": "Scales with the type's maximum takeoff weight and the destination.", "type": "integer", "example": 31000 }, "total_estimate_pence": { "type": "integer", "example": 127000 } }, "type": "object" } }, "type": "object" }, "V1FlightResource": { "required": [ "uuid", "status", "valid" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne flight from an aircraft's logbook.\n\nShaped around the question a bounty bot asks: did this tail number actually\nfly this leg, and did it finish? Hence `status` and `valid` sitting next to\nthe endpoints rather than being inferred from timestamps.\n\n`valid` deserves the explanation. The game marks a flight INVALID when it was\nflown in a way that does not count: teleporting, an implausible speed, a\nbroken client. The underlying column is `invalid`, a negative, and a bounty\ncheck reading `invalid == false` is one dropped `!` away from paying for a\ncheated flight. Publishing the positive makes the safe reading the natural\none. `invalid_reason` is preserved as `void_reason` so the detail is not lost.", "type": "string" }, "status": { "description": "Where the flight got to. `landed` is the only one that means finished.", "type": "string", "enum": [ "enroute", "landed" ], "example": "landed" }, "valid": { "description": "False when the game rejected the flight as implausible. Check this before paying anything against it.", "type": "boolean", "example": true }, "void_reason": { "description": "Why it was rejected, when `valid` is false.", "type": "string", "nullable": true }, "departure_icao": { "type": "string", "example": "EGCC", "nullable": true }, "arrival_icao": { "type": "string", "example": "EGLL", "nullable": true }, "pilot": { "description": "Username of whoever flew it.", "type": "string", "example": "SirLoin", "nullable": true }, "job_uuid": { "description": "The job this leg belonged to, for cross-referencing against /jobs/{uuid}.", "type": "string", "nullable": true }, "job_number": { "type": "integer", "nullable": true }, "leg_uuid": { "type": "string", "nullable": true }, "distance_nm": { "type": "number", "format": "float", "example": 152.4, "nullable": true }, "hours": { "type": "number", "format": "float", "example": 1.2, "nullable": true }, "takeoff_at": { "type": "string", "format": "date-time", "nullable": true }, "landed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1FlightResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1FlightResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 4 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 187 } }, "type": "object" } }, "type": "object" }, "V1FundTransfer": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\n`remaining_transferable_pence` is here so a payment queue does not have to\nattempt the next payment to find out whether it will clear. It is the same\nfigure GET /companies/{icao}/finances reports and the same one the website's\ntransfer form displays, because all three read\nPayments\\CalculateMaxTransferableAction.\n\n`recipient_type` distinguishes a pilot from a company explicitly rather than\nleaving a client to guess from the shape of `to`. Company ICAOs and usernames\ncan look alike, and paying the wrong party is not a recoverable mistake.", "type": "string", "example": "success" }, "data": { "required": [ "amount_pence", "from", "to", "recipient_type" ], "properties": { "amount_pence": { "type": "integer", "example": 500000 }, "from": { "description": "Sending company ICAO.", "type": "string", "example": "BLW" }, "to": { "description": "Pilot username or company ICAO — see recipient_type.", "type": "string", "example": "SirLoin" }, "recipient_type": { "type": "string", "enum": [ "pilot", "company" ], "example": "pilot" }, "reference": { "type": "string", "example": "Bounty: KSFO-YSSY in G-ABCD", "nullable": true }, "source_balance_pence": { "description": "The sender's balance after the transfer.", "type": "integer", "example": 2950000 }, "remaining_transferable_pence": { "description": "How much more may be moved right now. Not the balance: loan obligations are reserved and the month's profit bounds it. Read this instead of attempting a payment to see if it fits.", "type": "integer", "example": 1200000 } }, "type": "object" } }, "type": "object" }, "V1GroupDemandResource": { "required": [ "uuid", "count" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne group of passengers or cargo wanting to move.\n\n`collaborative` is the field that decides whether a company other than the\nowner can fly it. Collaborative demand can be released to a pool for anyone to\npick up; ordinary demand belongs to whoever generated it. A tool looking for\nwork released by other airlines filters on this.\n\n`price_pence` is what the demand is worth, not what any particular company will\nreceive. Revenue depends on the job built around it, what it costs to fly, and,\nfor collaborative work, the partnership's revenue-sharing terms. Publishing it\nas a job's earnings would mislead.\n\n`metadata` passes through as the game's own structure. It carries per-commodity\ndetail that varies by type and is still growing.", "type": "string" }, "departure_icao": { "type": "string", "example": "EGCC", "nullable": true }, "arrival_icao": { "type": "string", "example": "EGLL", "nullable": true }, "count": { "description": "How many passengers, or how much cargo.", "type": "integer", "example": 42 }, "status": { "type": "string", "example": "available", "nullable": true }, "collaborative": { "description": "True if this can be released to the pool for another company to fly.", "type": "boolean", "example": false }, "price_pence": { "description": "What the demand is worth. NOT what a company will earn: that depends on the job built around it and, for collaborative work, the partnership terms.", "type": "integer", "example": 250000, "nullable": true }, "distance_nm": { "type": "number", "format": "float", "nullable": true }, "pricing_class": { "type": "string", "nullable": true }, "metadata": { "description": "Per-commodity detail in the game's own shape. Varies by type.", "type": "object", "nullable": true }, "expires_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "V1GroupDemandResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1GroupDemandResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 8 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 372 } }, "type": "object" } }, "type": "object" }, "V1GroupResource": { "required": [ "uuid", "name", "type", "identifiers" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA named set of airport, country or aircraft-type identifiers a company reuses\nin filters and hireability rules. `identifiers` is a plain array of strings —\nairport idents, country codes or aircraft type ICAOs depending on `type` — not\na list of related objects, matching how the game stores them.", "type": "string" }, "name": { "type": "string", "example": "European Hubs" }, "type": { "type": "string", "enum": [ "airports", "countries", "aircraft" ], "example": "airports" }, "identifiers": { "type": "array", "items": { "type": "string" }, "example": [ "EGLL", "EGCC" ] }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1GroupResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1GroupResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1HireResult": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nThe outcome of POST /hire-aircraft, which has two of them.\n\nThe usual one is a job: you hired the aircraft, the job was created, and you\nare on it. The other is that hiring at a rank you do not yet hold APPLIES for\nthat rank, and until somebody approves the application there is no job of\nyours to hand back.\n\nThat second case is a success, not an error, which is why it is a field rather\nthan a 422. A client must check `pending_roster_application` before reading\n`job`, because on the pending path `job` is null and the work is genuinely not\ndone yet.", "type": "string", "example": "success" }, "data": { "required": [ "pending_roster_application" ], "properties": { "pending_roster_application": { "description": "True when hiring applied for a rank you do not hold yet. Nothing has been flown and `job` is null until the application is approved.", "type": "boolean", "example": false }, "job": { "oneOf": [ { "$ref": "#/components/schemas/V1JobResource" } ], "nullable": true, "description": "The job created by the hire. Null when the rank application is still pending." } }, "type": "object" } }, "type": "object" }, "V1Hireability": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "registration", "allow_hire" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "allow_hire": { "description": "Whether other players can see and hire this aircraft.", "type": "boolean", "example": true }, "filters": { "description": "Passed through as the game's own structure, because it is still growing and freezing a v1 vocabulary for it now would be a promise we would have to break.", "type": "object", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1HireableAircraftResource": { "required": [ "registration" ], "properties": { "registration": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne aircraft somebody else is offering for hire.\n\nEverything in this list has already passed the eligibility checks in\nGetHireableAircraftAction: rank constraints for the caller, and the\ncharter-ready rules (not frozen, not in service, has a position, no overdue\nmaintenance, not on a job). So a client does not have to filter it again, and\nshould not try: the rules are richer than anything reproducible from these\nfields, which is exactly why v1 reuses that action rather than rebuilding it.\n\nThe owner's hire `filters` are NOT published. They are the seller's private\nconfiguration, they are already applied to produce this list, and their shape\nis still moving. Publishing them would freeze it and leak a stranger's setup.", "type": "string", "example": "G-ABCD" }, "type_icao": { "type": "string", "example": "C172", "nullable": true }, "manufacturer": { "type": "string", "example": "Cessna", "nullable": true }, "model": { "type": "string", "example": "172 Skyhawk", "nullable": true }, "owner_icao": { "description": "The company offering it.", "type": "string", "example": "BLW", "nullable": true }, "owner_name": { "type": "string", "nullable": true }, "location_icao": { "description": "Where it stands. You fly from here.", "type": "string", "example": "EGCC", "nullable": true }, "seats": { "properties": { "economy": { "type": "integer", "example": 4 }, "business": { "type": "integer", "example": 0 }, "first": { "type": "integer", "example": 0 } }, "type": "object" }, "cargo_capacity_kg": { "type": "integer", "example": 500, "nullable": true }, "flight_hours": { "type": "number", "format": "float", "example": 412.5 } }, "type": "object" }, "V1HireableAircraftResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1HireableAircraftResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 63 } }, "type": "object" } }, "type": "object" }, "V1JobConstraints": { "required": [ "status", "data" ], "properties": { "status": { "description": "The result of a demand release.\n\n`released` is a COUNT, because one call can release many pieces at once and a\nbare success would leave a tool unable to tell \"released forty\" from \"matched\nnothing\". Zero is an ordinary answer rather than an error: a tool sweeping for\nurgent demand on a schedule will usually find none.", "type": "string", "example": "success" }, "data": { "description": "Why you cannot accept this job, from the same evaluator the accept flow uses. An OPEN object: constraint types are still being added, so render what you find rather than switching on fixed keys.", "type": "object" } }, "type": "object" }, "V1JobLegResource": { "required": [ "uuid", "status" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nNO MONEY, for the same reason as JobResource and one more besides. Bluestar's\nown handoff notes that financial fields appearing incidentally in general job\nresponses are a previously reported information-exposure problem, and that\ntheir client deliberately ignores them. The right answer on our side is not to\nput them in a list response at all: money comes from a dedicated endpoint that\ncan enforce view-job-details on its own.", "type": "string", "example": "0caf1cc7-6735-4d5c-894e-b3f9bafc7ace" }, "job_uuid": { "type": "string", "nullable": true }, "job_number": { "type": "integer", "example": 1234, "nullable": true }, "sequence": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "landed" }, "departure_icao": { "type": "string", "example": "KSFO", "nullable": true }, "arrival_icao": { "type": "string", "example": "YSSY", "nullable": true }, "distance_nm": { "type": "integer", "example": 6450, "nullable": true }, "aircraft_registration": { "type": "string", "example": "G-ABCD", "nullable": true }, "pilot": { "description": "The player who accepted the job, if any. Username only.", "type": "string", "example": "SirLoin", "nullable": true }, "required_seats": { "properties": { "economy": { "type": "integer", "example": 8 }, "business": { "type": "integer", "example": 0 }, "first": { "type": "integer", "example": 0 } }, "type": "object" }, "scheduled_at": { "type": "string", "nullable": true }, "departed_at": { "type": "string", "nullable": true }, "landed_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true } }, "type": "object" }, "V1JobLegResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1JobLegResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 4 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 180 } }, "type": "object" } }, "type": "object" }, "V1JobPrerequisites": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "description": "What must be flown before this job can be. Collaborative chains are only flyable in order. An OPEN object, for the same reason as constraints.", "type": "object" } }, "type": "object" }, "V1JobResource": { "required": [ "uuid", "status" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nIdentified by `uuid` and the human-facing `number`. No internal `id`.\n\nNO MONEY here, deliberately. Job pay is computed (GetJobUnlockedRevenueAction),\nnot a column, so including it would mean an action call per row and a list\nendpoint that gets slower the more jobs you have. Money belongs on a\nsingle-job endpoint where it is computed once, behind view-job-details. Adding\na field later is allowed by the v1 contract; removing one is not, so leaving\nit out now is the reversible choice.", "type": "string", "example": "0caf1cc7-6735-4d5c-894e-b3f9bafc7ace" }, "number": { "type": "integer", "example": 1234, "nullable": true }, "status": { "type": "string", "example": "in-progress" }, "ferry": { "type": "boolean", "example": false }, "distance_nm": { "type": "integer", "example": 210, "nullable": true }, "aircraft_registration": { "type": "string", "example": "G-ABCD", "nullable": true }, "legs": { "type": "array", "items": { "properties": { "uuid": { "type": "string" }, "sequence": { "type": "integer", "example": 1 }, "status": { "type": "string", "example": "landed" }, "departure_icao": { "type": "string", "example": "EGLL", "nullable": true }, "arrival_icao": { "type": "string", "example": "EGKK", "nullable": true }, "distance_nm": { "type": "integer", "example": 105, "nullable": true } }, "type": "object" } }, "accepted_at": { "type": "string", "nullable": true }, "departed_at": { "type": "string", "nullable": true }, "completed_at": { "type": "string", "nullable": true } }, "type": "object" }, "V1JobResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1JobResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 7 } }, "type": "object" } }, "type": "object" }, "V1JobRevenue": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only, no resource class.\n\nGetJobRevenueAction returns a plain array rather than a model, so there is\nnothing for a JsonResource to wrap and adding one would be a pass-through that\nonly existed to hold this attribute. The spec still needs the shape declared\nsomewhere, because tests/TestCase.php validates every /api response against\nstorage/api-docs/index.json, so it lives here.\n\nThe unlocked/locked split is FSCharter's payment model, not a display choice:\na multi-leg journey pays out at its final destination, so revenue attached to a\njob whose passengers are still travelling is not the company's yet. Both\nnumbers are always present and always pence.", "type": "string", "example": "success" }, "data": { "required": [ "job_uuid", "unlocked_pence", "locked_pence" ], "properties": { "job_uuid": { "type": "string", "example": "9c1f8f6e-4f0a-4a4a-9c7e-0f2b1d3e4a5b" }, "unlocked_pence": { "description": "Earned. Every leg this company operated on these journeys is complete.", "type": "integer", "example": 1250000 }, "locked_pence": { "description": "Not payable yet: the journey continues beyond this job. Not a deduction.", "type": "integer", "example": 340000 }, "unlocked_demand": { "description": "Demand journey UUIDs making up unlocked_pence.", "type": "array", "items": { "type": "string" } }, "locked_demand": { "type": "array", "items": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "V1LeftCompany": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "icao", "left" ], "properties": { "icao": { "type": "string", "example": "BLW" }, "left": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "V1LoanProductResource": { "required": [ "uuid", "name" ], "properties": { "uuid": { "description": "What POST /companies/{icao}/loans takes as `product`.", "type": "string" }, "name": { "type": "string", "example": "Standard Business Loan" }, "description": { "type": "string", "nullable": true }, "interest_rate": { "description": "A FRACTION range, not a percentage: 0.08 is eight per cent. min and max are equal on a fixed-rate product.", "properties": { "min": { "type": "number", "format": "float", "example": 0.06 }, "max": { "type": "number", "format": "float", "example": 0.12 }, "slides_with_amount": { "description": "When true the rate depends on how much you borrow and for how long, so only a quote gives the real figure.", "type": "boolean" } }, "type": "object" }, "term_cycles": { "description": "Allowed repayment terms, in game pay cycles.", "properties": { "min": { "type": "integer", "example": 4 }, "max": { "type": "integer", "example": 24 } }, "type": "object" }, "premium": { "description": "Only available to a subscribed account.", "type": "boolean" }, "minimum_aoc_level": { "description": "The operating certificate needed to borrow this. Null means any.", "type": "string", "example": "medium", "nullable": true } }, "type": "object" }, "V1LoanProductResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, though there are only six products.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1LoanProductResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" }, "V1LoanResource": { "required": [ "uuid", "outstanding_pence" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne loan.\n\n`outstanding_pence` is the field that matters most, and not only because it is\nthe debt. The FSC-4029 transfer ceiling is the balance minus the FULL\noutstanding obligation across every active loan, so this is the number that\nexplains why a company with money in the bank cannot move it. GET /finances\nreports the ceiling; this says what it is made of.\n\nTwo interest rates, because the game has two and confusing them misprices\neverything: `interest_rate` is over the whole term, `per_cycle_rate` is what\nis applied each cycle. Publishing only one would leave clients guessing which.", "type": "string" }, "product": { "description": "The lender and rate band this was borrowed under.", "type": "string", "example": "Commercial Term Loan", "nullable": true }, "principal_pence": { "description": "What was originally borrowed.", "type": "integer", "example": 50000000 }, "outstanding_pence": { "description": "Still owed. Subtracted in full from the transfer ceiling.", "type": "integer", "example": 31200000 }, "term_cycles": { "type": "integer", "example": 24 }, "original_term_cycles": { "description": "Differs from `term_cycles` once early repayments have shortened the loan.", "type": "integer", "example": 36, "nullable": true }, "interest_rate": { "description": "Over the whole term, not per cycle.", "type": "number", "format": "float", "example": 0.185, "nullable": true }, "per_cycle_rate": { "description": "Applied each cycle. This is the one that compounds.", "type": "number", "format": "float", "example": 0.0071, "nullable": true }, "settled": { "description": "True once nothing is outstanding.", "type": "boolean", "example": false }, "taken_out_at": { "type": "string", "format": "date-time" }, "closed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1LoanResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1LoanResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1MailMessageResource": { "required": [ "uuid", "subject", "read", "archived" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne message in your mailbox.\n\n`body` is HTML. The game stores it that way: a player-sent message is written\nas markdown and converted server-side before it is saved, and system messages\nare rendered from templates. There is no markdown source kept to hand back, so\na client that wants plain text has to strip it.\n\n`from` is a string rather than a user object, because a message's sender is\noften not a player at all: `sender_id` is null for anything the game itself\nsent. `from_username` is populated only when a real player sent it, so a\nclient that wants to link to a profile has something reliable to test.", "type": "string" }, "subject": { "type": "string", "example": "Runway works at EGLL" }, "body": { "description": "HTML. Player-written mail is authored as markdown and converted before storage.", "type": "string" }, "from": { "description": "Display name of the sender. \"FSCharter\" for anything the game sent.", "type": "string", "example": "FSCharter" }, "from_username": { "description": "Set only when a real player sent it. Null for system mail.", "type": "string", "nullable": true }, "read": { "type": "boolean" }, "archived": { "type": "boolean" }, "read_at": { "type": "string", "format": "date-time", "nullable": true }, "received_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1MailMessageResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "No `unread` count is injected here, unlike the internal collection. That made\nthe list's shape depend on who was asking and cost an extra query on every\npage; GET /api/v1/mail/unread-count answers it on its own.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1MailMessageResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 4 } }, "type": "object" } }, "type": "object" }, "V1MeResource": { "required": [ "status", "data" ], "properties": { "status": { "description": "GET /api/v1/me\n\nPUBLIC CONTRACT. Third-party tools parse this. Fields may be ADDED; they\nmust not be renamed, retyped or removed for the life of v1. If a field\nhere needs to change shape, that is v2.\n\nNote this is a separate class from GetUserStatisticsResource by design,\neven though the two overlap. That one describes what the statistics dialog\nneeds and is free to follow the dialog. This one cannot follow anything.", "type": "string", "example": "success" }, "data": { "required": [ "uuid", "username", "hours" ], "properties": { "uuid": { "type": "string", "example": "1dd1ffd2-1a46-4b09-9dba-289948ec7466" }, "username": { "type": "string", "example": "SirLoin" }, "avatar": { "type": "string", "nullable": true }, "first_name": { "type": "string", "nullable": true }, "last_name": { "type": "string", "nullable": true }, "email": { "description": "Your own address. Never published about anyone else.", "type": "string", "nullable": true }, "pending_email": { "description": "An address change awaiting the verification link. Null when there is none.", "type": "string", "nullable": true }, "premium": { "type": "boolean" }, "member_since": { "type": "string", "example": "2024-01-01T00:00:00.000000Z", "nullable": true }, "flights": { "type": "integer", "example": 412 }, "rank": { "properties": { "name": { "type": "string", "example": "Senior First Officer" }, "level": { "type": "integer", "example": 4 } }, "type": "object", "nullable": true }, "hours": { "properties": { "total": { "type": "number", "format": "float", "example": 1204.5 }, "category": { "properties": { "SEP": { "type": "number", "format": "float", "example": 10.5 }, "MEP": { "type": "number", "format": "float", "example": 20 }, "BIZ": { "type": "number", "format": "float", "example": 30 }, "REG": { "type": "number", "format": "float", "example": 40 }, "SRA": { "type": "number", "format": "float", "example": 50 }, "LRA": { "type": "number", "format": "float", "example": 60 }, "HEL": { "type": "number", "format": "float", "example": 70 } }, "type": "object" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1NetWorth": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nThe three small money payloads: net worth, the recurring-payment summary, and\nthe AOC level after an upgrade.", "type": "string", "example": "success" }, "data": { "description": "Net worth in pence. Assets plus bank balance minus outstanding debt, floored at zero. GET /net-worth/assets itemises the assets half.", "type": "integer", "example": 125000000 } }, "type": "object" }, "V1NetWorthAssetResource": { "required": [ "uuid", "value_pence" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne thing the company owns, at the value the net-worth check uses.\n\n`value_pence` is the RECORDED value, which is not necessarily what the asset\nwould sell for today. That distinction is the whole reason the endpoint is\nuseful: an aircraft transfer is refused when it would take net worth negative,\nand the figure subtracted is this one. A client comparing against a market\nvaluation would predict the wrong answer.\n\n`type` is a plain word rather than the internal model class. `model_type`\nholds a PHP namespace, which is an implementation detail and would freeze our\ndirectory layout into a public contract.", "type": "string" }, "name": { "type": "string", "example": "G-ABCD", "nullable": true }, "type": { "description": "What kind of thing it is, in plain words rather than an internal class name.", "type": "string", "enum": [ "aircraft", "building", "operations-centre", "other" ], "example": "aircraft" }, "value_pence": { "description": "The RECORDED value, which is what the net-worth check subtracts. Not necessarily the current market value.", "type": "integer", "example": 4250000 }, "recorded_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "V1NetWorthAssetResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1NetWorthAssetResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 2 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 64 } }, "type": "object" } }, "type": "object" }, "V1NotamResource": { "required": [ "uuid", "title", "message", "type" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA notice the company has posted for its own pilots. No expiry field exists —\nthe game has none, so this contract does not invent one.", "type": "string" }, "title": { "type": "string", "example": "Runway works at EGLL" }, "message": { "type": "string", "example": "Expect delays into Heathrow this weekend." }, "type": { "type": "string", "enum": [ "announcement", "info", "important" ], "example": "info" }, "posted_by": { "description": "Username of whoever posted it. Null if the account no longer exists.", "type": "string", "example": "SirLoin", "nullable": true }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1NotamResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1NotamResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1NotificationPreferenceResource": { "required": [ "notification", "name", "email", "fsmail", "is_default" ], "properties": { "notification": { "description": "Notification uuid. This is what PATCH takes.", "type": "string" }, "slug": { "type": "string", "example": "partnership-invitation-received" }, "name": { "type": "string", "example": "Partnership invitation received" }, "description": { "type": "string", "nullable": true }, "group": { "description": "What the website groups it under, e.g. \"Partnerships\".", "type": "string", "nullable": true }, "email": { "type": "boolean" }, "fsmail": { "type": "boolean" }, "is_default": { "description": "True when you have never changed this one, so the values above are the notification's own defaults.", "type": "boolean" }, "discord_webhook_configured": { "description": "Null unless you hold update-global-notification-preferences.", "type": "boolean", "nullable": true } }, "type": "object" }, "V1NotificationPreferenceResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated: this is the complete list of a company's notifications, around\nthirty of them, and a settings screen wants all of them at once. toArray() is\ndeliberately not overridden, because there is no pagination envelope to pass\nthrough.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1NotificationPreferenceResource" } } }, "type": "object" }, "V1OperationsCentreResource": { "required": [ "uuid", "airport_icao" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\n`size` and `country` are the two fields that matter, because those are what\nthe requirement checks compare against: several building and agreement\nvariants need an operations centre of at least a given size IN THAT COUNTRY.\nA client holding this list plus GET /agreement-variants can tell a user why a\npurchase is unavailable without sending a request that fails.", "type": "string" }, "size": { "description": "Compare against `requires.minimum_operations_centre_size` on a variant.", "type": "string", "example": "large" }, "airport_icao": { "type": "string", "example": "EGCC", "nullable": true }, "airport_name": { "type": "string", "nullable": true }, "country": { "description": "ISO country code. Requirements are per country, not per airport.", "type": "string", "example": "GB", "nullable": true } }, "type": "object" }, "V1OperationsCentreResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1OperationsCentreResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1PartnershipDissolved": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "uuid", "dissolved" ], "properties": { "uuid": { "description": "The alliance that no longer exists, for ANY of its members.", "type": "string" }, "name": { "type": "string", "nullable": true }, "dissolved": { "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "V1PartnershipInvitation": { "required": [ "status", "data" ], "properties": { "status": { "description": "Revenue sharing, which has THREE states rather than two.\n\nOn, off, and disabling-but-not-finished. Publishing only the boolean would let\na tool report an alliance as switched off while collaborative money was still\nbeing settled between its members.", "type": "string", "example": "success" }, "data": { "required": [ "uuid" ], "properties": { "uuid": { "description": "The partnership involved.", "type": "string" }, "invited": { "description": "Present when a company was invited.", "type": "string", "nullable": true }, "revoked": { "description": "Present when an outstanding invitation was withdrawn.", "type": "string", "nullable": true }, "removed": { "description": "Present when a joined member was removed.", "type": "string", "nullable": true }, "declined": { "description": "Present when a company declined its own invitation.", "type": "string", "nullable": true }, "left": { "description": "Present when a company left of its own accord.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1PartnershipMemberResource": { "required": [ "icao" ], "properties": { "icao": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne company's place in an alliance, and the terms it is on.\n\nThe two percentages are the point of the endpoint and they are NOT the same\nthing, which is worth stating because the names invite confusion.\n`contribution_percentage` is what this company puts in; `share_percentage` is\nwhat it takes out. An alliance can legitimately run them asymmetrically, so a\nclient must not treat one as derivable from the other.\n\n`last_payout_pence` is the most recent settlement, which is the closest thing\nto evidence that revenue sharing is actually working.\n\n`accepted_at` being null means an outstanding INVITATION rather than a member.\nPublished rather than filtered out, so the same shape serves both the members\nlist and the pending list.", "type": "string", "example": "BSC" }, "name": { "type": "string", "nullable": true }, "contribution_percentage": { "description": "What this company puts IN. Not the inverse of share.", "type": "number", "format": "float", "example": 25, "nullable": true }, "share_percentage": { "description": "What this company takes OUT.", "type": "number", "format": "float", "example": 30, "nullable": true }, "last_payout_pence": { "type": "integer", "example": 1250000, "nullable": true }, "accepted_at": { "description": "Null for an outstanding invitation rather than a member.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1PartnershipMemberResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PartnershipMemberResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 4 } }, "type": "object" } }, "type": "object" }, "V1PartnershipResource": { "required": [ "uuid", "name" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne alliance between companies.\n\n`lead_icao` is the field that decides what a client may offer to do. Renaming\nthe alliance, inviting companies, setting revenue-sharing terms and dissolving\nit are all the LEAD member's calls, and every one of those endpoints refuses\nanybody else. Publishing it means a tool can hide the buttons rather than\ndiscovering the refusals one at a time.\n\n`members` carries ICAOs only. The terms each member is on live behind\nGET /partnerships/{uuid}/members, because they are pivot data and repeating\nthem here would make listing a company's alliances quadratic in members.\n\n`revenue_sharing_enabled` and `pending_cleanup` are both published because\ndisabling is not instant: the flag goes false while in-flight collaborative\nbookkeeping settles, and a tool that only read the first field would report an\nalliance as fully switched off while money was still moving.", "type": "string" }, "name": { "type": "string", "example": "Silver Alliance" }, "code": { "description": "What other companies quote to find this alliance. Unique across the game.", "type": "string", "example": "SILVER", "nullable": true }, "colour": { "type": "string", "example": "#C0C0C0", "nullable": true }, "lead_icao": { "description": "The company that runs the alliance. Only it can rename, invite, set terms or dissolve, so check this before offering those actions.", "type": "string", "example": "BLW", "nullable": true }, "members": { "description": "ICAOs of every company involved, accepted or invited. Terms are in /partnerships/{uuid}/members.", "type": "array", "items": { "type": "string" }, "example": [ "BLW", "BSC" ] }, "revenue_sharing_enabled": { "type": "boolean", "example": true }, "pending_cleanup": { "description": "True while a disable is still settling in-flight collaborative bookkeeping. The alliance is not fully switched off until this is false.", "type": "boolean", "example": false }, "formed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1PartnershipResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PartnershipResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 4 } }, "type": "object" } }, "type": "object" }, "V1PaymentItemResource": { "required": [ "uuid", "amount_pence", "direction" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne line behind a payment: the fuel, the landing fee, the crew cost that\ntogether made up a total in the ledger.\n\n`amount_pence` is always POSITIVE and `direction` carries the sign, matching\nPaymentResource. The underlying row stores the amount alongside an `inverse`\nflag, and a client adding up a breakdown should not have to know that.\n\n`verify_url` and `link` are NOT published. They point at internal screens, so\nthey would be a promise to keep the website's URL structure stable.", "type": "string" }, "description": { "type": "string", "example": "Landing fee at EGLL", "nullable": true }, "amount_pence": { "description": "Always positive. `direction` carries the sign.", "type": "integer", "example": 31000 }, "direction": { "description": "`debit` reduced the payment total, `credit` added to it.", "type": "string", "enum": [ "debit", "credit" ], "example": "debit" }, "type": { "type": "string", "nullable": true }, "is_net_worth_asset": { "description": "True when this line bought something that counts toward net worth, such as an aircraft.", "type": "boolean", "example": false } }, "type": "object" }, "V1PaymentItemResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PaymentItemResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 6 } }, "type": "object" } }, "type": "object" }, "V1PaymentResource": { "required": [ "uuid", "amount_pence", "direction" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne line of a company's ledger. Shaped around the question Bluestar's bounty\nbot asks before it sends money: have I already paid this reference, this\namount, to this person?\n\n`counterparty` is resolved to a NAME rather than left as an account number,\nwhich is the one design decision worth explaining. The underlying row stores\n`source_account_number` and `destination_account_number`, and the internal API\nhands those out. A client then has to resolve each one through a user lookup to\nfind out who it paid, which is a second request per row and the reason their\nbot needed GET /api/users at all. Resolving it here costs one eager load and\nremoves that whole step.\n\n`direction` says whether money left or arrived, so a duplicate check does not\nhave to infer it by comparing account numbers against its own. It carries the\ngame's own `incoming`/`outgoing` values rather than a shortened alias, because a\ntranslation layer between the enum and the contract is one more thing that can\ndrift.", "type": "string", "example": "7c2e1a94-3b5d-4e6f-8a0b-1c2d3e4f5a6b" }, "reference": { "description": "The note set when the payment was made. What a duplicate check matches on.", "type": "string", "example": "Bounty: KSFO-YSSY in G-ABCD", "nullable": true }, "amount_pence": { "type": "integer", "example": 500000 }, "direction": { "description": "The game's own values, passed through rather than shortened: `outgoing` if money left this company, `incoming` if it arrived.", "type": "string", "enum": [ "incoming", "outgoing" ], "example": "outgoing" }, "counterparty": { "description": "Who the money went to or came from, already resolved. Null where the other side is not an account we can name, such as a fee that leaves the economy.", "properties": { "type": { "type": "string", "enum": [ "pilot", "company" ], "example": "pilot" }, "name": { "description": "A username for a pilot, an ICAO for a company.", "type": "string", "example": "SirLoin" } }, "type": "object", "nullable": true }, "description": { "type": "string", "example": "Transfer from Bluestar Airways to SirLoin", "nullable": true }, "category": { "type": "string", "example": "manual-transfer", "nullable": true }, "status": { "type": "string", "example": "complete", "nullable": true }, "reversed": { "type": "boolean", "example": false }, "balance_after_pence": { "description": "The account balance once this payment had been applied.", "type": "integer", "example": 2950000, "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "V1PaymentResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PaymentResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 12 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 240 } }, "type": "object" } }, "type": "object" }, "V1PeopleChanged": { "required": [ "status", "data" ], "properties": { "status": { "description": "The generic delete confirmation, shared by roles, ranks and constraints.\n\nOne schema rather than three, because there is genuinely nothing to say beyond\n\"this uuid is gone\", and three identical schemas would suggest a difference\nthat does not exist.", "type": "string", "example": "success" }, "data": { "properties": { "invited": { "description": "Present on a hire. These people now have a pending invitation; they are not staff until they accept.", "type": "array", "items": { "type": "string" }, "nullable": true }, "removed": { "description": "Present on a fire. Their roles at this company were stripped too.", "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } }, "type": "object" }, "V1PerspectiveResource": { "required": [ "uuid", "name", "default", "data" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA saved view of the operations cockpit. `data` is published as a real JSON\nobject. The internal API stores (and transmits) this column as base64-encoded\nJSON text; a public contract should not require a client to decode base64\njust to read a settings blob, so v1 decodes it on the way out and expects a\nplain object on the way in.", "type": "string" }, "name": { "type": "string", "example": "Ops Overview" }, "default": { "description": "Whether this is the company's default view.", "type": "boolean" }, "data": { "description": "The saved lens/filter/camera state. Shape is internal and may grow; treat it as opaque.", "type": "object" }, "created_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1PerspectiveResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PerspectiveResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" }, "V1PilotAchievementResource": { "required": [ "unlocked", "secret" ], "properties": { "name": { "description": "Null for a secret achievement this player has not unlocked.", "type": "string", "example": "First Solo", "nullable": true }, "description": { "type": "string", "nullable": true }, "unlocked": { "type": "boolean" }, "secret": { "type": "boolean" }, "points": { "description": "Progress toward this achievement, not a score.", "type": "integer" }, "unlocked_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1PilotAchievementResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PilotAchievementResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 18 } }, "type": "object" } }, "type": "object" }, "V1PilotLogbookResource": { "required": [ "status", "hours_flown" ], "properties": { "company_icao": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne logged flight. Every field is a SNAPSHOT taken when the entry was minted,\nwhich is why the company and aircraft appear as plain strings rather than\nrelations: the entry survives the company being wound up or the aircraft\nbeing sold, and it keeps saying what was true at the time.\n\nA logbook entry has no public identifier. The table has an auto-increment id\nand no uuid, and publishing a row id would leak how many flights the game has\nrecorded. The flight is identified by what it was: who, when, and between\nwhich two airports.\n\nThe internal resource repeats this entire payload again nested under\n`job_leg.job`. That is not reproduced here.", "type": "string", "example": "FSC", "nullable": true }, "company_name": { "type": "string", "nullable": true }, "departure": { "type": "string", "example": "EGLL", "nullable": true }, "arrival": { "type": "string", "example": "KJFK", "nullable": true }, "departure_name": { "type": "string", "nullable": true }, "arrival_name": { "type": "string", "nullable": true }, "distance_nmi": { "type": "number", "format": "float" }, "aircraft_tail_number": { "type": "string", "nullable": true }, "aircraft_type": { "type": "string", "example": "B738", "nullable": true }, "aircraft_category": { "type": "string", "example": "SRA", "nullable": true }, "hours_flown": { "type": "number", "format": "float" }, "status": { "type": "string", "enum": [ "enroute", "landed" ], "example": "landed" }, "takeoff_at": { "type": "string", "format": "date-time", "nullable": true }, "landed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1PilotLogbookResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PilotLogbookResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 9 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 412 } }, "type": "object" } }, "type": "object" }, "V1PilotStatisticsResource": { "required": [ "username", "hours" ], "properties": { "username": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nAnother player's public flying record. Deliberately the SAME shape as the\nflying half of V1MeResource, so a client can render itself and somebody else\nwith one component.\n\nNo real name, no email, and no active flight. The internal statistics\nendpoint returns the player's full name (nulled unless you are them) and\ntheir in-progress flight with airports and aircraft attached. A real name is\nnot ours to publish about somebody else, and where a player is right now is\nlive operational detail rather than a profile.", "type": "string", "example": "SirLoin" }, "avatar": { "type": "string", "nullable": true }, "member_since": { "type": "string", "format": "date-time", "nullable": true }, "flights": { "type": "integer", "example": 412 }, "rank": { "properties": { "name": { "type": "string", "example": "Senior First Officer" }, "level": { "type": "integer", "example": 4 } }, "type": "object", "nullable": true }, "hours": { "properties": { "total": { "type": "number", "format": "float", "example": 1204.5 }, "category": { "type": "object" } }, "type": "object" } }, "type": "object" }, "V1Preferences": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass.\n\nA flat {key: value} map of your settings, with every key the game has\npresent. Not the settings SCREEN: the internal endpoint returns section\ntitles, descriptions and dropdown options with the values spliced in, and a\nfrozen contract has no business publishing our UI copy. See\nPublishedPreferences.\n\nNew preferences will be ADDED to this map as the game gains them, so treat it\nas open. `banking.currency` is display-only, incidentally: nothing is\nconverted, only the symbol changes.", "type": "string", "example": "success" }, "data": { "description": "Keys are dotted preference names. More may appear over time.", "properties": { "banking.currency": { "description": "Display symbol only; no conversion happens.", "type": "string", "example": "£" }, "units.weight": { "type": "string", "example": "kg" }, "emails.re_engagement_emails": { "type": "boolean" }, "marketplace.show_job_search_assistant": { "type": "boolean" }, "marketplace.persistent_pilot_mode": { "type": "boolean" } }, "type": "object" } }, "type": "object" }, "V1PricingStrategyResource": { "required": [ "uuid", "discount", "state" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA pricing strategy: a standing rule that discounts fares across whole SETS of\nroutes, for a period.\n\nNOT a fare. Fares live on a route. A strategy selects routes by filter and\ndiscounts whatever it matches, which is why one company can run several and why\nchanging a strategy's filters can move prices on routes nobody named.\n\n`state` collapses three timestamps into one word, because working out whether a\nstrategy is actually applying right now means checking paused_at, ends_at AND\nstarts_at against the clock, and every client would otherwise reimplement that.\nThe three states are not interchangeable: `paused` is reversible, `ended` is\nnot.\n\n`discount` is a FRACTION, the game's own unit. Publishing it as a percentage\nwould create two conventions for one number and guarantee somebody applies the\nwrong one.", "type": "string" }, "name": { "type": "string", "nullable": true }, "discount": { "description": "A FRACTION, not a percentage: 0.15 is fifteen per cent off. The game's own unit.", "type": "number", "format": "float", "example": 0.15 }, "state": { "description": "Computed from the timestamps. `scheduled` has not started yet, `active` is applying now, `paused` is reversibly stopped, `ended` is permanent.", "type": "string", "enum": [ "scheduled", "active", "paused", "ended" ], "example": "active" }, "route_filters": { "description": "Which routes it applies to, in the game's own selector shape. Open-ended: new filter kinds get added.", "type": "object", "nullable": true }, "demand_filters": { "description": "Which demand it applies to, same shape.", "type": "object", "nullable": true }, "class_settings": { "description": "Per-cabin overrides, in the game's own shape.", "type": "object", "nullable": true }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "paused_at": { "type": "string", "format": "date-time", "nullable": true }, "created_at": { "type": "string", "format": "date-time" } }, "type": "object" }, "V1PricingStrategyResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PricingStrategyResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1PricingStrategyTypeResource": { "required": [ "uuid", "slug", "name", "target" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nA kind of filter a pricing strategy can select by. `target` says whether it\npicks ROUTES or DEMAND, which matters because a strategy carries both a\nroute_filters and a demand_filters object and putting a filter in the wrong\none silently matches nothing.\n\n`filter_definition` is NOT published. It is the form schema our own UI renders\nthe filter builder from; freezing it would freeze that form.", "type": "string" }, "slug": { "type": "string", "example": "route-departure-country" }, "name": { "type": "string", "example": "Departure Country" }, "description": { "type": "string", "nullable": true }, "target": { "description": "Which half of a strategy this filter belongs in.", "type": "string", "enum": [ "route", "demand" ], "example": "route" } }, "type": "object" }, "V1PricingStrategyTypeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PricingStrategyTypeResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 21 } }, "type": "object" } }, "type": "object" }, "V1PrivilegeResource": { "required": [ "slug", "name" ], "properties": { "slug": { "description": "The identifier used everywhere else: in role definitions, and in every 403 message v1 returns.", "type": "string", "example": "transfer-funds" }, "name": { "type": "string", "example": "Transfer funds" }, "description": { "type": "string", "nullable": true } }, "type": "object" }, "V1PrivilegeResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated. A fixed set decided by the game or by the company's own ladder,\nnot a list that grows with activity, so paging it would make clients write a\nloop that runs once. See AircraftServiceScheduleResourceCollection.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1PrivilegeResource" } } }, "type": "object" }, "V1Quote": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\n`redeem_at` and `redeem_with` are echoed rather than left to documentation. A\nquote is bound to an exact URL and an exact set of request fields, and the two\nfailure modes (\"URL mismatch\", \"hash mismatch\") are otherwise very hard to\ndebug from the outside: a caller sees a rejection with no indication of what it\nwas expecting. Returning the binding means a mismatch is visible by comparing\ntwo things in one log line.", "type": "string", "example": "success" }, "data": { "required": [ "quote", "for", "value_pence", "redeem_at" ], "properties": { "quote": { "description": "Send this as `quote` with the purchase.", "type": "string", "example": "f2b8c1d4-5a6e-4f7b-8c9d-0e1f2a3b4c5d" }, "for": { "type": "string", "enum": [ "agreement", "field-service" ], "example": "agreement" }, "value_pence": { "description": "The price, locked to you until expires_at.", "type": "integer", "example": 1250000 }, "expires_at": { "description": "After this, re-quote. Spending an expired quote fails.", "type": "string", "format": "date-time", "nullable": true }, "redeem_at": { "description": "The only URL this quote may be spent at.", "type": "string", "example": "/api/v1/companies/BLW/agreements" }, "redeem_with": { "description": "Request fields that must match exactly when spending it. Send these values verbatim.", "type": "object", "additionalProperties": { "type": "string" } } }, "type": "object" } }, "type": "object" }, "V1RankConstraintResource": { "required": [ "uuid", "type" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne rule limiting what a rank may fly.\n\n`data` passes through as the game's own structure, and that is a deliberate\nrefusal to invent a v1 vocabulary. Constraint types are open-ended (weight\nceilings, type allowlists, range limits, and more get added), and each type\nreads `data` differently. Freezing a shape here would mean rejecting\nconstraints the website itself accepts as soon as a new type appears.\n\n`type` is the constraint type's name (as listed by /constraint-types), which a\nclient keys off to interpret `data`.", "type": "string" }, "type": { "description": "Constraint type name, as listed by /api/v1/constraint-types. Decides how to read `data`.", "type": "string", "example": "aircraft-category" }, "description": { "type": "string", "nullable": true }, "data": { "description": "The constraint's own parameters, in the game's shape. Read according to `type`. Deliberately not flattened into named fields: constraint types are still being added.", "type": "object", "nullable": true } }, "type": "object" }, "V1RankConstraintResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RankConstraintResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" }, "V1RankProgressionResource": { "required": [ "uuid", "required_hours" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne rung of the rank ladder: fly this many hours at rank A and rank B unlocks.\n\nPublished as a pair of rank uuids rather than nested rank objects, because the\nladder is a graph and a client wants to assemble it. Fetch the ranks once from\nGET /companies/{icao}/ranks and join; nesting would repeat every rank on both\nsides of every edge.", "type": "string" }, "from_rank_uuid": { "description": "Null for an entry point: a rank reachable without holding another first.", "type": "string", "nullable": true }, "from_rank": { "type": "string", "example": "Second Officer", "nullable": true }, "to_rank_uuid": { "type": "string" }, "to_rank": { "type": "string", "example": "First Officer", "nullable": true }, "required_hours": { "description": "Hours that must be flown before the next rank unlocks.", "type": "number", "format": "float", "example": 50 } }, "type": "object" }, "V1RankProgressionResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "NOT paginated. A fixed set decided by the game or by the company's own ladder,\nnot a list that grows with activity, so paging it would make clients write a\nloop that runs once. See AircraftServiceScheduleResourceCollection.", "type": "string", "example": "success" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RankProgressionResource" } } }, "type": "object" }, "V1RecurringPaymentResource": { "required": [ "uuid", "amount_pence", "active" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne standing cost: a slot rent, a loan repayment, a salary.\n\n`active` is published rather than left to be worked out from\n`deactivated_at`, because a suspended payment still sits in the table and a\ntool summing \"what leaves the account each cycle\" would otherwise count money\nthat is not going anywhere.\n\n`recipient_account_number` is deliberately NOT published, matching the ledger.\nv1 never hands out account numbers.", "type": "string" }, "description": { "type": "string", "example": "Commercial Term Loan repayment", "nullable": true }, "amount_pence": { "description": "What leaves the account each cycle.", "type": "integer", "example": 2450000 }, "active": { "description": "False once suspended. A suspended payment still appears here but costs nothing.", "type": "boolean", "example": true }, "inactive_reason": { "type": "string", "nullable": true }, "cycles_completed": { "type": "integer", "example": 7 }, "final_cycle": { "description": "Null for an open-ended cost such as a slot rent.", "type": "integer", "example": 24, "nullable": true }, "amount_paid_pence": { "description": "Total paid so far across all cycles.", "type": "integer", "example": 17150000 }, "starts_at": { "type": "string", "format": "date-time", "nullable": true }, "ends_at": { "type": "string", "format": "date-time", "nullable": true }, "last_charged_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1RecurringPaymentResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RecurringPaymentResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 12 } }, "type": "object" } }, "type": "object" }, "V1RecurringPaymentSummary": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "total", "count" ], "properties": { "total": { "description": "What leaves the account each cycle, across every active recurring payment.", "type": "integer", "example": 8450000 }, "count": { "type": "integer", "example": 12 }, "categories": { "description": "The same total split by what the money is for: loans, agreements, buildings, other.", "type": "object" } }, "type": "object" } }, "type": "object" }, "V1RegionResource": { "required": [ "code", "name" ], "properties": { "code": { "description": "UN M49 code. Joins to `region` on GET /countries.", "type": "integer", "example": 154 }, "name": { "type": "string", "example": "Northern Europe" } }, "type": "object" }, "V1RegionResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "description": "Paginated, like every other v1 collection, even though this table is small.\n`per_page` accepts up to 100.", "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RegionResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 100 }, "total": { "type": "integer", "example": 25 } }, "type": "object" } }, "type": "object" }, "V1RestrictionPenaltyResource": { "required": [ "uuid", "penalty_pence" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne leg that was re-priced down for spoilage: a group booking held too long\nbefore it flew. `penalty_pence` is the difference the internal record stores\nas two separate before/after prices; publishing the difference directly is\nwhat a client actually wants rather than making it subtract two numbers.", "type": "string" }, "departure": { "type": "string", "example": "EGLL", "nullable": true }, "arrival": { "type": "string", "example": "KJFK", "nullable": true }, "aircraft_tail_number": { "type": "string", "nullable": true }, "pilot": { "description": "Pilot username, or null if the job carries none.", "type": "string", "nullable": true }, "original_price_pence": { "type": "integer" }, "final_price_pence": { "type": "integer" }, "penalty_pence": { "description": "original_price_pence minus final_price_pence.", "type": "integer" }, "completed_at": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1RestrictionPenaltyResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RestrictionPenaltyResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 20 }, "total": { "type": "integer", "example": 4 } }, "type": "object" } }, "type": "object" }, "V1RestrictionPenaltySummary": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass — the internal action already returns a plain array, not a model.\n\nTotal spoilage penalties for the current calendar month. No `month`\nparameter is exposed; see GetCompanyRestrictionPenaltiesSummaryAction.", "type": "string", "example": "success" }, "data": { "required": [ "total_pence", "breach_count", "period" ], "properties": { "total_pence": { "type": "integer", "example": 240000 }, "breach_count": { "type": "integer", "example": 6 }, "period": { "required": [ "start", "end", "label" ], "properties": { "start": { "type": "string", "format": "date-time" }, "end": { "type": "string", "format": "date-time" }, "label": { "type": "string", "example": "August 2026" } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1RevenueSharing": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "uuid", "revenue_sharing_enabled", "pending_cleanup" ], "properties": { "uuid": { "type": "string" }, "revenue_sharing_enabled": { "type": "boolean", "example": true }, "pending_cleanup": { "description": "True while a disable is still settling in-flight collaborative bookkeeping. Not fully off until this is false.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "V1RoleMembersChanged": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "uuid" ], "properties": { "uuid": { "description": "The role that changed.", "type": "string" }, "added": { "type": "array", "items": { "type": "string" }, "nullable": true }, "removed": { "type": "array", "items": { "type": "string" }, "nullable": true } }, "type": "object" } }, "type": "object" }, "V1RosterEntryResource": { "required": [ "uuid", "username", "status" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne pilot's place on a company's roster.\n\nThe underlying row has FOUR timestamps that together form a state machine:\napplied, accepted, rejected, terminated. Publishing them raw would make every\nclient reimplement the same three-way comparison to answer \"is this pilot\nactive\", and some would get it wrong: an accepted entry that was later\nterminated still has its accepted_at set.\n\nSo `status` is computed once, here, and the timestamps are published\nalongside it for anyone who wants the history.", "type": "string" }, "username": { "type": "string", "example": "SirLoin" }, "rank": { "description": "The rank they fly at, which decides what they may take.", "type": "string", "example": "First Officer", "nullable": true }, "rank_uuid": { "type": "string", "nullable": true }, "status": { "description": "Computed from the timestamps so a client does not have to. `pending` is waiting on a decision; `active` flies for you now.", "type": "string", "enum": [ "pending", "active", "rejected", "former" ], "example": "active" }, "total_paid_pence": { "description": "What this pilot has earned here in total.", "type": "integer", "example": 4250000 }, "applied_at": { "type": "string", "format": "date-time", "nullable": true }, "accepted_at": { "type": "string", "format": "date-time", "nullable": true }, "left_at": { "description": "Set when they were removed or left. The column is `terminated_at`; renamed here because most departures are not terminations.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1RosterEntryResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RosterEntryResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" }, "V1RouteDemandPreview": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\n`demand_summary` is the SAME shape a real route reports, so a client comparing\na prospective route against one it already flies is comparing like with like\nrather than reshaping one side first. Both go through Api\\Support\\DemandSummary.\n\n`priced_at` echoes the fares the preview was run with. Demand responds to\nprice, so a summary without the prices it was produced at is not a comparable\nnumber, and echoing them means a cached or logged response is still meaningful\nlater.", "type": "string", "example": "success" }, "data": { "required": [ "departure_icao", "arrival_icao", "demand_summary" ], "properties": { "departure_icao": { "type": "string", "example": "KSFO" }, "arrival_icao": { "type": "string", "example": "YSSY" }, "distance_nm": { "type": "integer", "example": 6450, "nullable": true }, "demand_summary": { "description": "Always an object with an integer per cabin, including explicit zeroes. Identical shape to a route's own demand_summary.", "properties": { "economy": { "type": "integer", "example": 42 }, "business": { "type": "integer", "example": 8 }, "first": { "type": "integer", "example": 2 }, "cargo": { "type": "integer", "example": 0 }, "freight": { "type": "integer", "example": 0 } }, "type": "object" }, "priced_at": { "description": "The fares this preview was run with. Demand responds to price, so the summary is only meaningful alongside them.", "properties": { "economy_pence": { "type": "integer", "example": 25000 }, "business_pence": { "type": "integer", "example": 90000 }, "first_pence": { "type": "integer", "example": 180000 } }, "type": "object" } }, "type": "object" } }, "type": "object" }, "V1RouteNumbers": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nRoute numbers already in use at a company.\n\nPublished as STRINGS, deliberately. Route numbers are a varchar column and can\ncarry a carrier prefix (\"BLW101\"), so typing them as integers would be wrong for\nexactly the companies that use them properly. This is also the one place in v1\nwhere a number-looking field is a string on purpose: job numbers are integers,\nand that difference is real rather than an inconsistency.", "type": "string", "example": "success" }, "data": { "required": [ "icao", "taken" ], "properties": { "icao": { "type": "string", "example": "BLW" }, "taken": { "description": "Numbers already used. Creating a route with one of these is refused, so pick something else.", "type": "array", "items": { "type": "string" }, "example": [ "101", "102", "BLW200" ] } }, "type": "object" } }, "type": "object" }, "V1RouteResource": { "required": [ "uuid", "demand_summary" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\n`demand_summary` is ALWAYS an object with an integer for every cabin, even when\na route has no demand at all. That is a deliberate fix rather than a\npass-through: the internal column is a PHP array, so an empty one serialises as\n`[]` and a never-populated one as `null`, meaning a client currently has to\ntreat three different shapes as \"zero\" and cannot tell a real zero from a\nmissing field. Bluestar's Route Locker write-up lists this as its first\nrequested improvement, and it is the sort of thing a public contract should\nsimply not do to people.\n\n`minimums` and `prices` are nested rather than flat `economy_minimum`,\n`first_price` and so on. A bot that wants to lock a route reads and writes\nminimums as a unit, and the nesting matches the PATCH body, so the same shape\ngoes out and comes back.", "type": "string", "example": "0caf1cc7-6735-4d5c-894e-b3f9bafc7ace" }, "number": { "type": "string", "example": "BLW101", "nullable": true }, "departure_icao": { "type": "string", "example": "KSFO", "nullable": true }, "arrival_icao": { "type": "string", "example": "YSSY", "nullable": true }, "distance_nm": { "type": "integer", "example": 6450, "nullable": true }, "enabled": { "description": "Whether the route is currently flyable. `user` is the company's own switch; `system` is FSCharter's.", "properties": { "user": { "type": "boolean", "example": true }, "system": { "type": "boolean", "example": true } }, "type": "object" }, "minimums": { "description": "Minimum bookings before the route will generate a job. Always integers.", "properties": { "economy": { "type": "integer", "example": 10 }, "business": { "type": "integer", "example": 2 }, "first": { "type": "integer", "example": 0 }, "cargo": { "type": "number", "format": "float", "example": 0 }, "freight": { "type": "number", "format": "float", "example": 0 } }, "type": "object" }, "prices": { "description": "Fares in pence.", "properties": { "economy_pence": { "type": "integer", "example": 25000 }, "business_pence": { "type": "integer", "example": 90000 }, "first_pence": { "type": "integer", "example": 180000 } }, "type": "object" }, "demand_summary": { "description": "ALWAYS an object with an integer per cabin, including explicit zeroes. Never [] and never null.", "properties": { "economy": { "type": "integer", "example": 0 }, "business": { "type": "integer", "example": 0 }, "first": { "type": "integer", "example": 0 }, "cargo": { "type": "integer", "example": 0 }, "freight": { "type": "integer", "example": 0 } }, "type": "object" } }, "type": "object" }, "V1RouteResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1RouteResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 124 } }, "type": "object" } }, "type": "object" }, "V1SaleWithdrawn": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "registration", "listed" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "listed": { "description": "False, now that the listing is gone.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "V1ServiceAutomation": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nThree small settings responses that share a shape: each echoes back the\nsetting that was just changed, so a client can confirm the new state without\na second request.\n\nThey are separate schemas rather than one loose object because a published\ncontract should let a generated client know exactly which fields come back\nfrom which call.", "type": "string", "example": "success" }, "data": { "required": [ "registration", "check", "automatic" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "check": { "description": "Service type slug.", "type": "string", "example": "a-check" }, "automatic": { "description": "When true, the game books this check itself as it falls due. When false, an overdue check will ground the aircraft.", "type": "boolean", "example": true } }, "type": "object" } }, "type": "object" }, "V1ServiceBooking": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nReturns the SCHEDULE ROW rather than a bare success, so a client can show the\neffect (hours reset, no longer overdue) without a second request.\n\n`charged` exists because the two routes to a serviced aircraft differ on money:\nA and B checks are free, and a field service on a general aviation aircraft\ncosts a fee. A tool spending someone else's money should be able to tell them\nit did, and should not have to infer it from the check letter.", "type": "string", "example": "success" }, "data": { "required": [ "registration", "check", "via", "charged" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "check": { "type": "string", "example": "a-check" }, "via": { "description": "`unrestricted` for an A or B check done where the aircraft stands; `field` for a paid C or D check on a general aviation aircraft.", "type": "string", "enum": [ "unrestricted", "field" ], "example": "unrestricted" }, "charged": { "description": "Whether a fee left the company's account. True only for field service.", "type": "boolean", "example": false }, "schedule": { "oneOf": [ { "$ref": "#/components/schemas/V1AircraftServiceScheduleResource" } ], "nullable": true, "description": "This check's schedule row after booking." } }, "type": "object" } }, "type": "object" }, "V1ServiceRecordResource": { "required": [ "uuid", "check" ], "properties": { "uuid": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne completed or in-progress maintenance check.\n\n`complete_at` being null is the useful signal rather than an omission: it\nmeans the check is STILL RUNNING. A tool that books maintenance needs to tell\n\"serviced an hour ago\" from \"in the hangar right now\", because the second one\nmeans the aircraft cannot take a job yet.\n\n`initiated_by` is null for automated services. That is not missing data, it\nis the answer: nobody pressed anything, the automation did it.", "type": "string" }, "check": { "description": "Service type slug, matching the schedule endpoint.", "type": "string", "example": "a-check" }, "check_name": { "type": "string", "example": "A Check", "nullable": true }, "airport_icao": { "description": "Where the work was done.", "type": "string", "example": "EGCC", "nullable": true }, "initiated_by": { "description": "Username, or null when the automation booked it.", "type": "string", "example": "SirLoin", "nullable": true }, "started_at": { "type": "string", "format": "date-time", "nullable": true }, "complete_at": { "description": "Null means the check is still in progress and the aircraft is unavailable.", "type": "string", "format": "date-time", "nullable": true }, "in_progress": { "description": "The same fact as a null `complete_at`, stated positively.", "type": "boolean", "example": false }, "notes": { "type": "string", "nullable": true } }, "type": "object" }, "V1ServiceRecordResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1ServiceRecordResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 3 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 112 } }, "type": "object" } }, "type": "object" }, "V1SimbriefResource": { "required": [ "airframe_mappings" ], "properties": { "passenger_weight_kg": { "description": "Kilograms per passenger. Null means the game default.", "type": "number", "format": "float", "example": 84, "nullable": true }, "airframe_mappings": { "description": "Which SimBrief airframe to use for one of your aircraft, or for a whole aircraft type.", "type": "array", "items": { "required": [ "aircraft_identifier", "aircraft_type", "simbrief_airframe_id" ], "properties": { "aircraft_identifier": { "description": "A tail number, or an aircraft type ICAO, depending on aircraft_type.", "type": "string", "example": "G-ABCD" }, "aircraft_type": { "type": "string", "enum": [ "tail_number", "aircraft_type" ] }, "simbrief_airframe_id": { "type": "string", "example": "A20N" } }, "type": "object" } } }, "type": "object" }, "V1StaffResource": { "required": [ "username" ], "properties": { "username": { "description": "PUBLIC CONTRACT (v1). Fields may be ADDED; never renamed, retyped or removed.\n\nOne member of staff: somebody with a ROLE at the company, as opposed to\nsomebody on the pilot roster who merely flies for it.\n\n`roles` is a list of names rather than the full role objects. A staff list\nwants to say \"Alice is Ops Manager\"; a client that needs the privileges behind\nthat name asks GET /companies/{icao}/roles once and joins on it, rather than\nreceiving the same privilege lists repeated on every row.\n\nNo email, no internal id. A username is how the game identifies a person and\nit is the only handle any v1 write takes.", "type": "string", "example": "SirLoin" }, "roles": { "description": "Role names held at this company. Look the names up in GET /companies/{icao}/roles for their privileges.", "type": "array", "items": { "type": "string" }, "example": [ "Ops Manager" ] }, "accepted_at": { "description": "When they accepted the invitation. Null while still pending.", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "V1StaffResourceCollection": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/V1StaffResource" } }, "current_page": { "type": "integer", "example": 1 }, "last_page": { "type": "integer", "example": 1 }, "per_page": { "type": "integer", "example": 50 }, "total": { "type": "integer", "example": 8 } }, "type": "object" } }, "type": "object" }, "V1TailNumberValidation": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass.\n\nWhether a registration is legal for this airframe in this country, and still\nfree. `valid` false with a `message` is a normal 200: the question was\nanswered. A 404 means the country or the type does not exist, and a 422 means\nthat country registers no aircraft of this kind at all.", "type": "string", "example": "success" }, "data": { "required": [ "valid" ], "properties": { "valid": { "type": "boolean" }, "message": { "description": "Why not. Absent when valid.", "type": "string", "nullable": true } }, "type": "object" } }, "type": "object" }, "V1TransferPreview": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see JobRevenueSchema for why these exist without a resource class.\n\nWhat transferring this aircraft would do to the sender's net worth.\n\n`would_be_refused` is the field that earns the endpoint. The rule is that a\ntransfer may not take net worth below zero, and it lives in the transfer\naction where it belongs. Reporting only the three numbers would leave every\nclient to reimplement the comparison, and any that got it wrong would find\nout during the second half of a Bounties reserve, with the plane already\nmoved.", "type": "string", "example": "success" }, "data": { "required": [ "registration", "net_worth_pence", "asset_value_pence", "net_worth_after_pence", "would_be_refused" ], "properties": { "registration": { "type": "string", "example": "G-ABCD" }, "net_worth_pence": { "description": "The sending company's net worth now.", "type": "integer", "example": 125000000 }, "asset_value_pence": { "description": "What this aircraft counts for. The RECORDED asset value where one exists, which is what the check subtracts, falling back to the calculated value.", "type": "integer", "example": 4250000 }, "net_worth_after_pence": { "description": "May be negative, which is precisely the case worth catching.", "type": "integer", "example": 120750000 }, "would_be_refused": { "description": "True when the transfer would take net worth below zero and POST /transfer would answer 422.", "type": "boolean", "example": false } }, "type": "object" } }, "type": "object" }, "V1UnlockedRevenue": { "required": [ "status", "data" ], "properties": { "status": { "type": "string", "example": "success" }, "data": { "description": "How much of the job's revenue legs already flown have unlocked. Not the job's total: see GET /jobs/{uuid}/revenue for that. An open object, because what contributes to unlocking is the game's to change.", "type": "object" } }, "type": "object" }, "V1UnreadMailCount": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only; see RouteNumbersSchema for why these exist without a resource\nclass. Unread mail in the INBOX: archived messages are not counted even if\nthey were never read, matching the badge the website shows.", "type": "string", "example": "success" }, "data": { "required": [ "unread" ], "properties": { "unread": { "type": "integer", "example": 3 } }, "type": "object" } }, "type": "object" }, "V1WebhooksUpdated": { "required": [ "status", "data" ], "properties": { "status": { "description": "Schema only. A COUNT, not the values: a Discord webhook URL is a live\ncredential and v1 has no endpoint that hands one back, not even the one that\njust set it. See UpdateNotificationWebhooksAction.", "type": "string", "example": "success" }, "data": { "required": [ "updated" ], "properties": { "updated": { "type": "integer", "example": 2 } }, "type": "object" } }, "type": "object" } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "A personal access token from Profile → API Access, or a token obtained through the OAuth authorisation-code flow. Send it as `Authorization: Bearer `. Revoking a token takes effect on the very next request." } } }, "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Public API v1", "description": "Frozen for the life of v1. Fields may be added; never renamed, retyped or removed." } ] }