diff --git a/package.json b/package.json
index 6e524e2..8601a0a 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,7 @@
   "files": [
     "build"
   ],
-  "main": "./spec.json",
+  "main": "./build/spec.json",
   "scripts": {
     "start": "vite",
     "build": "node --experimental-strip-types ./script/build.ts",
diff --git a/src/spec/chunks.ts b/src/spec/chunks.ts
index b50ed94..0049d4f 100644
--- a/src/spec/chunks.ts
+++ b/src/spec/chunks.ts
@@ -78,7 +78,7 @@ export const buildingCommonMethods = (base: string) => {
   const queueResultSchema = (description: string) => ({
     ...response200(description, {
       type: 'object',
-      required: ['building', 'status'],
+      required: ['building', 'status', 'buildings'],
       properties: {
         building: {
           type: 'object',
@@ -90,6 +90,7 @@ export const buildingCommonMethods = (base: string) => {
           required: ['id', 'level', 'pending_build'],
         },
         status: statusSchema(),
+        buildings: { $ref: '#/components/schemas/buildings_list' },
       },
     }),
     ...response500(),
@@ -98,8 +99,12 @@ export const buildingCommonMethods = (base: string) => {
   const buildingViewResultSchema = (description: string) => ({
     ...response200(description, {
       type: 'object',
-      required: ['building', 'status'],
-      properties: { building: { $ref: '#/components/schemas/building' }, status: statusSchema() },
+      required: ['building', 'status', 'buildings'],
+      properties: {
+        building: { $ref: '#/components/schemas/building' },
+        status: statusSchema(),
+        buildings: { $ref: '#/components/schemas/buildings_list' },
+      },
     }),
     ...response500(),
   });
@@ -146,8 +151,11 @@ export const buildingCommonMethods = (base: string) => {
         responses: {
           ...response200('Instantly destroys a building.', {
             type: 'object',
-            required: ['status'],
-            properties: { status: statusSchema() },
+            required: ['status', 'buildings'],
+            properties: {
+              status: statusSchema(),
+              buildings: { $ref: '#/components/schemas/buildings_list' },
+            },
           }),
           ...response500(),
         },
@@ -278,21 +286,97 @@ export const speciesSchema = () => {
       'growth_affinity',
     ],
     properties: {
-      name: { type: 'string' },
-      description: { type: 'string' },
-      min_orbit: { type: 'integer', minimum: 1, maximum: 7 },
-      max_orbit: { type: 'integer', minimum: 1, maximum: 7 },
-      manufacturing_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      deception_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      research_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      management_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      farming_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      mining_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      science_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      environmental_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      political_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      trade_affinity: { type: 'integer', minimum: 1, maximum: 7 },
-      growth_affinity: { type: 'integer', minimum: 1, maximum: 7 },
+      name: {
+        type: 'string',
+        description:
+          'The name of the species. Limited to 30 characters, cannot be blank, and cannot contain @, &, <, >, or ;.',
+      },
+      description: {
+        type: 'string',
+        description:
+          'The species description. Limited to 1024 characters and cannot contain < or >.',
+      },
+      min_orbit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description:
+          'The closest orbit this species can inhabit, where 1 is nearest the star. Every orbit from min_orbit to max_orbit inclusive costs a point. Must be less than or equal to max_orbit.',
+      },
+      max_orbit: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description:
+          'The furthest orbit this species can inhabit, where 1 is nearest the star. Every orbit from min_orbit to max_orbit inclusive costs a point. Must be greater than or equal to min_orbit.',
+      },
+      manufacturing_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in manufactured goods, such as ships.',
+      },
+      deception_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in spying.',
+      },
+      research_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in upgrading buildings.',
+      },
+      management_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in the speed of building.',
+      },
+      farming_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in food production.',
+      },
+      mining_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in mineral production.',
+      },
+      science_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description:
+          '7 is best. Determines advantages in energy, propulsion, and other technologies.',
+      },
+      environmental_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in waste and water management.',
+      },
+      political_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in managing population happiness.',
+      },
+      trade_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in freight handling.',
+      },
+      growth_affinity: {
+        type: 'integer',
+        minimum: 1,
+        maximum: 7,
+        description: '7 is best. Determines advantages in colonization.',
+      },
     },
   };
 };
diff --git a/src/spec/components.ts b/src/spec/components.ts
index 14a352e..6e7e3c0 100644
--- a/src/spec/components.ts
+++ b/src/spec/components.ts
@@ -211,6 +211,52 @@ export const components = {
       required: ['food', 'water', 'energy', 'waste', 'ore', 'time'],
     },
 
+    // The lightweight per-building shape returned by get_buildings/repair_list — not the full
+    // `building` schema, since this is a list/grid view, not a single-building detail view.
+    buildings_list: {
+      type: 'object',
+      required: ['buildings'],
+      properties: {
+        buildings: {
+          type: 'object',
+          description: 'Keyed by building id.',
+          additionalProperties: {
+            type: 'object',
+            required: ['name', 'x', 'y', 'url', 'level', 'image', 'efficiency'],
+            properties: {
+              name: { type: 'string' },
+              x: { type: 'integer', minimum: -5, maximum: 5 },
+              y: { type: 'integer', minimum: -5, maximum: 5 },
+              url: { type: 'string' },
+              level: { type: 'integer' },
+              image: { type: 'string' },
+              efficiency: { type: 'integer' },
+              // Only included when the building is being built/upgraded.
+              pending_build: {
+                type: 'object',
+                properties: {
+                  seconds_remaining: { type: 'integer' },
+                  start: { type: 'string' },
+                  end: { type: 'string' },
+                },
+                required: ['seconds_remaining', 'start', 'end'],
+              },
+              // Only included when the building is working (Parks, Waste Recycling, etc).
+              work: {
+                type: 'object',
+                properties: {
+                  seconds_remaining: { type: 'integer' },
+                  start: { type: 'string' },
+                  end: { type: 'string' },
+                },
+                required: ['seconds_remaining', 'start', 'end'],
+              },
+            },
+          },
+        },
+      },
+    },
+
     building_production: {
       type: 'object',
       properties: {
diff --git a/src/spec/paths/body.ts b/src/spec/paths/body.ts
index 08410af..4f3c405 100644
--- a/src/spec/paths/body.ts
+++ b/src/spec/paths/body.ts
@@ -1,47 +1,16 @@
 import { requestBodySchema, response200, response500, security, statusSchema } from '../chunks.ts';
 
-// The lightweight per-building shape returned by get_buildings/repair_list — not the full
-// `building` schema (see components.ts), since this is a list/grid view, not a single-building
-// detail view.
-const buildingListEntrySchema = {
-  type: 'object',
-  required: ['name', 'x', 'y', 'url', 'level', 'image', 'efficiency'],
-  properties: {
-    name: { type: 'string' },
-    x: { type: 'integer', minimum: -5, maximum: 5 },
-    y: { type: 'integer', minimum: -5, maximum: 5 },
-    url: { type: 'string' },
-    level: { type: 'integer' },
-    image: { type: 'string' },
-    efficiency: { type: 'integer' },
-    // Only included when the building is being built/upgraded.
-    pending_build: {
-      type: 'object',
-      properties: {
-        seconds_remaining: { type: 'integer' },
-        start: { type: 'string' },
-        end: { type: 'string' },
-      },
-      required: ['seconds_remaining', 'start', 'end'],
-    },
-    // Only included when the building is working (Parks, Waste Recycling, etc).
-    work: {
-      type: 'object',
-      properties: {
-        seconds_remaining: { type: 'integer' },
-        start: { type: 'string' },
-        end: { type: 'string' },
-      },
-      required: ['seconds_remaining', 'start', 'end'],
-    },
-  },
-};
-
 export const body = {
   '/v2/body/get_status': {
     post: {
       ...security(),
 
+      ...requestBodySchema({
+        type: 'object',
+        required: ['body_id'],
+        properties: { body_id: { type: 'string' } },
+      }),
+
       responses: {
         ...response200('Returns information about the current state of the empire.', {
           type: 'object',
@@ -74,11 +43,7 @@ export const body = {
             type: 'object',
             required: ['buildings', 'body', 'status'],
             properties: {
-              buildings: {
-                type: 'object',
-                description: 'Keyed by building id.',
-                additionalProperties: buildingListEntrySchema,
-              },
+              buildings: { $ref: '#/components/schemas/buildings_list' },
               body: {
                 type: 'object',
                 required: ['surface_image'],
@@ -113,11 +78,7 @@ export const body = {
             type: 'object',
             required: ['buildings', 'body', 'status'],
             properties: {
-              buildings: {
-                type: 'object',
-                description: 'Keyed by building id.',
-                additionalProperties: buildingListEntrySchema,
-              },
+              buildings: { $ref: '#/components/schemas/buildings_list' },
               body: {
                 type: 'object',
                 required: ['surface_image'],
diff --git a/src/spec/paths/buildings/mercenariesguild.ts b/src/spec/paths/buildings/mercenariesguild.ts
index 8040cf9..00fe4b2 100644
--- a/src/spec/paths/buildings/mercenariesguild.ts
+++ b/src/spec/paths/buildings/mercenariesguild.ts
@@ -81,7 +81,7 @@ export const mercenariesGuild = {
       responses: {
         ...response200('Returns a list of spies that may be traded. Used with add_to_market.', {
           type: 'object',
-          required: ['spies', 'cargo_space_used_each', 'status'],
+          required: ['spies', 'status'],
           properties: {
             spies: {
               type: 'array',
@@ -95,7 +95,6 @@ export const mercenariesGuild = {
                 required: ['id', 'name', 'level'],
               },
             },
-            cargo_space_used_each: { type: 'integer' },
             status: statusSchema(),
           },
         }),
diff --git a/src/spec/paths/buildings/observatory.ts b/src/spec/paths/buildings/observatory.ts
index 39ae4b5..6b89c98 100644
--- a/src/spec/paths/buildings/observatory.ts
+++ b/src/spec/paths/buildings/observatory.ts
@@ -25,10 +25,52 @@ const starSchema = {
     name: { type: 'string' },
     x: { type: 'integer' },
     y: { type: 'integer' },
-    z: { type: 'integer' },
-    bodies: { type: 'array', items: { $ref: '#/components/schemas/body_status' } },
+    bodies: {
+      type: 'array',
+      items: {
+        type: 'object',
+        properties: {
+          id: { type: 'number' },
+          x: { type: 'number' },
+          y: { type: 'number' },
+          star_id: { type: 'number' },
+          star_name: { type: 'string' },
+          orbit: { type: 'number' },
+          type: { type: 'string' },
+          name: { type: 'string' },
+          image: { type: 'string' },
+          size: { type: 'number' },
+          notes: { type: 'string' },
+          zone: { type: 'string' },
+          station: {
+            type: 'object',
+            properties: {
+              id: { type: 'number' },
+              x: { type: 'number' },
+              y: { type: 'number' },
+              name: { type: 'string' },
+            },
+            required: ['id', 'x', 'y', 'name'],
+          },
+        },
+        required: [
+          'id',
+          'x',
+          'y',
+          'star_id',
+          'star_name',
+          'orbit',
+          'type',
+          'name',
+          'image',
+          'size',
+          'notes',
+          'zone',
+        ],
+      },
+    },
   },
-  required: ['id', 'color', 'name', 'x', 'y', 'z', 'bodies'],
+  required: ['id', 'color', 'name', 'x', 'y', 'bodies'],
 };
 
 export const observatory = {
diff --git a/src/spec/paths/buildings/park.ts b/src/spec/paths/buildings/park.ts
index 448f971..588a70c 100644
--- a/src/spec/paths/buildings/park.ts
+++ b/src/spec/paths/buildings/park.ts
@@ -31,7 +31,7 @@ const viewResultSchema = (description: string) => ({
           happiness: { type: 'integer' },
           can_throw: { type: 'integer', enum: [1, 0] },
         },
-        required: ['seconds_remaining', 'happiness', 'can_throw'],
+        required: [],
       },
     },
   }),
@@ -48,7 +48,7 @@ export const park = {
         happiness: { type: 'integer' },
         can_throw: { type: 'integer', enum: [1, 0] },
       },
-      required: ['seconds_remaining', 'happiness', 'can_throw'],
+      required: [],
     },
   }),
 
diff --git a/src/spec/paths/buildings/trade.ts b/src/spec/paths/buildings/trade.ts
index c5effa5..04a355e 100644
--- a/src/spec/paths/buildings/trade.ts
+++ b/src/spec/paths/buildings/trade.ts
@@ -504,9 +504,9 @@ export const trade = {
       responses: {
         ...response200('Lists waste chains (a default chain exists for the local star).', {
           type: 'object',
-          required: ['waste_chains', 'status'],
+          required: ['waste_chain', 'status'],
           properties: {
-            waste_chains: {
+            waste_chain: {
               type: 'array',
               items: {
                 type: 'object',
diff --git a/src/spec/paths/captcha.ts b/src/spec/paths/captcha.ts
index b5f8883..4144696 100644
--- a/src/spec/paths/captcha.ts
+++ b/src/spec/paths/captcha.ts
@@ -27,10 +27,10 @@ export const captcha = {
 
       ...requestBodySchema({
         type: 'object',
-        required: ['captcha_guid', 'captcha_solution'],
+        required: ['guid', 'solution'],
         properties: {
-          captcha_guid: { type: 'string', description: 'Must match the guid from fetch.' },
-          captcha_solution: { type: 'string', description: "The user's typed solution." },
+          guid: { type: 'string', description: 'Must match the guid from fetch.' },
+          solution: { type: 'string', description: "The user's typed solution." },
         },
       }),
 
diff --git a/src/spec/paths/empire.ts b/src/spec/paths/empire.ts
index 88c1b5e..203be67 100644
--- a/src/spec/paths/empire.ts
+++ b/src/spec/paths/empire.ts
@@ -7,12 +7,30 @@ import {
   statusSchema,
 } from '../chunks.ts';
 
+// The medals block shared by the view_profile and edit_profile responses. Distinct from the one in
+// view_public_profile, which omits `public` since every medal shown there is public by definition.
+const profileMedalsSchema = {
+  type: 'object',
+  description: 'Keyed by medal id.',
+  additionalProperties: {
+    type: 'object',
+    required: ['name', 'image', 'date', 'public', 'times_earned'],
+    properties: {
+      name: { type: 'string' },
+      image: { type: 'string' },
+      date: { type: 'string', format: 'date-time' },
+      public: { type: 'integer', enum: [1, 0] },
+      times_earned: { type: 'integer' },
+    },
+  },
+};
+
 export const empire = {
   '/v2/empire/is_name_available': {
     post: {
       responses: {
         ...response200(
-          'Returns a 1 if the name is available, or a throws an exception if it is not.',
+          'Returns a 1 if the name is available, or throws an exception if it is not. Throws 1000.',
           { type: 'integer', enum: [1, 0] }
         ),
         ...response500(),
@@ -21,7 +39,9 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['name'],
-        properties: { name: { type: 'string' } },
+        properties: {
+          name: { type: 'string', description: 'The name of the empire to search for.' },
+        },
       }),
     },
   },
@@ -31,7 +51,7 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Ends a session. Returns 1.', { type: 'integer', enum: [1] }),
+        ...response200('Ends a session. Returns 1. Throws 1006.', { type: 'integer', enum: [1] }),
         ...response500(),
       },
     },
@@ -40,11 +60,14 @@ export const empire = {
   '/v2/empire/login': {
     post: {
       responses: {
-        ...response200('Returns a session ID with empire and server status', {
-          type: 'object',
-          properties: { session_id: { type: 'string' }, status: statusSchema() },
-          required: ['session_id', 'status'],
-        }),
+        ...response200(
+          'Confirms the password matches the empire and returns a session id alongside the empire and server status. A session survives up to 2 hours of inactivity, so there is no need to log in again while an existing session is still valid. Throws 1004 and 1005.',
+          {
+            type: 'object',
+            properties: { session_id: { type: 'string' }, status: statusSchema() },
+            required: ['session_id', 'status'],
+          }
+        ),
         ...response500(),
       },
 
@@ -52,9 +75,22 @@ export const empire = {
         type: 'object',
         required: ['empire_name', 'password', 'api_key'],
         properties: {
-          empire_name: { type: 'string' },
-          password: { type: 'password' },
-          api_key: { type: 'string' },
+          empire_name: { type: 'string', description: 'The name of the empire.' },
+          password: {
+            type: 'string',
+            format: 'password',
+            description: 'The password to authenticate to the empire.',
+          },
+          api_key: {
+            type: 'string',
+            description:
+              "Your client's unique API key, identifying it from all other clients. See ApiKeys for details.",
+          },
+          browser: {
+            type: 'string',
+            description:
+              'Optional client identifier recorded against the session. Not part of the original API documentation.',
+          },
         },
       }),
     },
@@ -79,21 +115,56 @@ export const empire = {
   '/v2/empire/create': {
     post: {
       responses: {
-        ...response200('Creates a new empire and then returns an empire_id.', { type: 'string' }),
+        ...response200(
+          'Creates a new empire and returns its empire_id. The empire is not playable yet — either call update_species and then found, or skip the species step and call found directly. Throws 1000, 1001, 1002, and 1014. On a 1014 the error data carries fresh captcha information that must be used for the next attempt, since a captcha cannot be used more than once.',
+          { type: 'string' }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
-        required: ['name', 'password', 'password1', 'captcha_guid', 'captcha_solution'],
+        required: ['name', 'captcha_guid', 'captcha_solution'],
         properties: {
-          name: { type: 'string' },
-          password: { type: 'string' },
-          password1: { type: 'string' },
-          captcha_guid: { type: 'string' },
-          captcha_solution: { type: 'string' },
-          email: { type: 'string' },
-          invite_code: { type: 'string' },
+          name: { type: 'string', description: 'The name of the empire to create.' },
+          password: {
+            type: 'string',
+            description:
+              'The password to log in to the empire. Must be between 6 and 30 characters. Required unless you have a valid facebook_uid and facebook_token, and still recommended even when authenticating through Facebook.',
+          },
+          password1: {
+            type: 'string',
+            description:
+              'Retyping the password again. This must match password to succeed. Required whenever password is supplied.',
+          },
+          captcha_guid: {
+            type: 'string',
+            description: 'Must match the guid field returned by the fetch_captcha method.',
+          },
+          captcha_solution: {
+            type: 'string',
+            description: 'The text typed in by the user as the solution of the captcha.',
+          },
+          email: {
+            type: 'string',
+            description:
+              "The user's email address. Not required, but used for system vital functions like password recovery.",
+          },
+          facebook_uid: {
+            type: 'string',
+            description:
+              "A Facebook user id passed in through Lacuna's Facebook integration system. Optional, but required alongside facebook_token.",
+          },
+          facebook_token: {
+            type: 'string',
+            description:
+              "A Facebook access token passed in through Lacuna's Facebook integration system. Optional, but required alongside facebook_uid.",
+          },
+          invite_code: {
+            type: 'string',
+            description:
+              'A 36 character code that was sent to the user by a friend. Usable only once, it ensures that their friend gets a home planet in relatively close proximity to their own.',
+          },
         },
       }),
     },
@@ -103,7 +174,7 @@ export const empire = {
     post: {
       responses: {
         ...response200(
-          "Set up an empire on it's new home world. Once this method is called, the species can no longer be modified.",
+          'Sets up an empire on its new home world. Once this method is called, the species can no longer be modified. The returned welcome_message_id identifies an inbox message that starts the tutorial, so the user can be prompted to read it right away.',
           {
             type: 'object',
             required: ['session_id', 'welcome_message_id', 'status'],
@@ -121,15 +192,22 @@ export const empire = {
         type: 'object',
         required: ['empire_id', 'api_key'],
         properties: {
-          empire_id: { type: 'string' },
-          api_key: { type: 'string' },
-          invite_code: { type: 'string' },
+          empire_id: { type: 'string', description: 'The empire to found.' },
+          api_key: {
+            type: 'string',
+            description:
+              "Your client's unique API key, identifying it from all other clients. See ApiKeys for details.",
+          },
+          invite_code: {
+            type: 'string',
+            description: 'Deprecated here. Pass invite_code to the create method instead.',
+          },
         },
       }),
     },
   },
 
-  '/v2/empire/get_friend_invite_url': {
+  '/v2/empire/get_invite_friend_url': {
     post: {
       ...security(),
 
@@ -153,7 +231,7 @@ export const empire = {
 
       responses: {
         ...response200(
-          'Send an invitation code to a friend so that they can start in the same zone as your empire.',
+          'Sends an invitation code to a friend so that they can start in the same zone as your empire. Each not_sent entry pairs the address with the [code, message] reason it could not be invited.',
           {
             type: 'object',
             required: ['status'],
@@ -177,7 +255,18 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['email'],
-        properties: { email: { type: 'string' }, custom_message: { type: 'string' } },
+        properties: {
+          email: {
+            type: 'string',
+            description:
+              'The email address of your friend, or a comma separated string of email addresses.',
+          },
+          custom_message: {
+            type: 'string',
+            description:
+              'An optional message the user can type to invite their friend. Defaults to "I\'m having a great time with this new game called Lacuna Expanse. Come play with me." The empire name, friend code, and server URI are appended to whatever is sent.',
+          },
+        },
       }),
     },
   },
@@ -187,14 +276,17 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Returns information about the current state of the empire.', {
-          type: 'object',
-          required: ['empire', 'body'],
-          properties: {
-            server: { $ref: '#/components/schemas/server_status' },
-            empire: { $ref: '#/components/schemas/empire_status' },
-          },
-        }),
+        ...response200(
+          'Returns information about the current state of the empire. You should probably never call this directly — it is a wasted call, since the same data comes back in the status block of every relevant request. Throws 1002.',
+          {
+            type: 'object',
+            required: ['empire', 'server'],
+            properties: {
+              server: { $ref: '#/components/schemas/server_status' },
+              empire: { $ref: '#/components/schemas/empire_status' },
+            },
+          }
+        ),
         ...response500(),
       },
     },
@@ -241,15 +333,7 @@ export const empire = {
                 properties: {
                   description: { type: 'string' },
                   status_message: { type: 'string' },
-                  medals: {
-                    '{medal_id}': {
-                      name: { type: 'string' },
-                      image: { type: 'string' },
-                      date: { type: 'string', format: 'date-time' },
-                      public: { type: 'integer', enum: [1, 0] },
-                      times_earned: { type: 'integer' },
-                    },
-                  },
+                  medals: profileMedalsSchema,
                   city: { type: 'string' },
                   country: { type: 'string' },
                   notes: { type: 'string' },
@@ -287,7 +371,7 @@ export const empire = {
 
       responses: {
         ...response200(
-          'Edits properties of an empire. Returns the view_profile method. See also the view_profile and view_public_profile methods.',
+          'Edits properties of an empire. Returns the same payload as view_profile. Only the properties present in the request are updated. See also the view_profile and view_public_profile methods. Throws 1005 and 1009.',
           {
             type: 'object',
             required: ['profile', 'status'],
@@ -322,15 +406,7 @@ export const empire = {
                 properties: {
                   description: { type: 'string' },
                   status_message: { type: 'string' },
-                  medals: {
-                    '{medal_id}': {
-                      name: { type: 'string' },
-                      image: { type: 'string' },
-                      date: { type: 'string', format: 'date-time' },
-                      public: { type: 'integer', enum: [1, 0] },
-                      times_earned: { type: 'integer' },
-                    },
-                  },
+                  medals: profileMedalsSchema,
                   city: { type: 'string' },
                   country: { type: 'string' },
                   notes: { type: 'string' },
@@ -366,30 +442,138 @@ export const empire = {
         properties: {
           profile: {
             type: 'object',
+            description:
+              'The properties to be edited. Set one or all of them — only those set will be updated.',
             properties: {
-              description: { type: 'string' },
-              status_message: { type: 'string' },
-              public_medals: { type: 'array', items: { type: 'number' } },
-              city: { type: 'string' },
-              country: { type: 'string' },
-              notes: { type: 'string' },
-              skype: { type: 'string' },
-              player_name: { type: 'string' },
-              skip_happiness_warnings: { type: 'integer', enum: [1, 0] },
-              skip_resource_warnings: { type: 'integer', enum: [1, 0] },
-              skip_pollution_warnings: { type: 'integer', enum: [1, 0] },
-              skip_medal_messages: { type: 'integer', enum: [1, 0] },
-              skip_facebook_wall_posts: { type: 'integer', enum: [1, 0] },
-              skip_found_nothing: { type: 'integer', enum: [1, 0] },
-              skip_excavator_resources: { type: 'integer', enum: [1, 0] },
-              skip_excavator_glyph: { type: 'integer', enum: [1, 0] },
-              skip_excavator_plan: { type: 'integer', enum: [1, 0] },
-              skip_spy_recovery: { type: 'integer', enum: [1, 0] },
-              skip_probe_detected: { type: 'integer', enum: [1, 0] },
-              skip_attack_messages: { type: 'integer', enum: [1, 0] },
-              skip_incoming_ships: { type: 'integer', enum: [1, 0] },
-              email: { type: 'string', format: 'email' },
-              sitter_password: { type: 'string' },
+              description: {
+                type: 'string',
+                description:
+                  'A description of the empire. Limited to 1024 characters and cannot contain < or >.',
+              },
+              status_message: {
+                type: 'string',
+                description:
+                  "A message to indicate what you're doing, how you're feeling, or other status indicator. Limited to 100 characters, cannot be blank, and cannot contain @, &, <, >, or ;.",
+              },
+              public_medals: {
+                type: 'array',
+                items: { type: 'number' },
+                description:
+                  'The ids of the medals the user wishes to display in the public profile.',
+              },
+              city: {
+                type: 'string',
+                description:
+                  'The city in which the player resides. Limited to 100 characters and cannot contain @, &, <, >, or ;.',
+              },
+              country: {
+                type: 'string',
+                description:
+                  'The country in which the player resides. Limited to 100 characters and cannot contain @, &, <, >, or ;.',
+              },
+              notes: {
+                type: 'string',
+                description:
+                  'A text blob where the user can write down whatever they want to store in their account. Limited to 1024 characters and cannot contain @, &, <, >, or ;.',
+              },
+              skype: {
+                type: 'string',
+                description:
+                  'The username this player uses on Skype. Limited to 100 characters and cannot contain @, &, <, >, or ;.',
+              },
+              player_name: {
+                type: 'string',
+                description:
+                  'The real name or online identity of this player. Limited to 100 characters and cannot contain @, &, <, >, or ;.',
+              },
+              skip_happiness_warnings: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages about unhappy citizens. WARNING: these messages are there for your own protection — turn them off at your own risk.',
+              },
+              skip_resource_warnings: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages about a lack of resources to keep buildings running. WARNING: these messages are there for your own protection — turn them off at your own risk.',
+              },
+              skip_pollution_warnings: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages about excess waste causing pollution. WARNING: these messages are there for your own protection — turn them off at your own risk.',
+              },
+              skip_medal_messages: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  "Defaults to 0. Set to 1 to stop receiving messages about the medals they've earned.",
+              },
+              skip_facebook_wall_posts: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop messages being posted to their Facebook wall.',
+              },
+              skip_found_nothing: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages when excavators find nothing.',
+              },
+              skip_excavator_resources: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages when excavators find resources.',
+              },
+              skip_excavator_glyph: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages when excavators find glyphs.',
+              },
+              skip_excavator_plan: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages when excavators find plans.',
+              },
+              skip_spy_recovery: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving spy recovery messages ("I\'m ready to work. What do you need from me?").',
+              },
+              skip_probe_detected: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Defaults to 0. Set to 1 to stop receiving messages when a probe is detected.',
+              },
+              skip_attack_messages: {
+                type: 'integer',
+                enum: [1, 0],
+                description: 'Defaults to 0. Set to 1 to stop receiving messages about attacks.',
+              },
+              skip_incoming_ships: {
+                type: 'integer',
+                enum: [1, 0],
+                description:
+                  'Controls the display of incoming ships (own, allied, foreign) on the map display. Defaults to 0, which shows them. Set to 1 to hide them, which can improve browser responsiveness.',
+              },
+              email: {
+                type: 'string',
+                format: 'email',
+                description:
+                  'An email address that can be used for system functions like password recovery. Must either resemble an email address or be empty.',
+              },
+              sitter_password: {
+                type: 'string',
+                description:
+                  'A password that can be safely given to account sitters and alliance members. Must be between 6 and 30 characters.',
+              },
             },
           },
         },
@@ -402,163 +586,158 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Provides a list of data that is publicly known about this empire', {
-          type: 'object',
-          properties: {
-            profile: {
-              type: 'object',
-              properties: {
-                city: { type: 'string' },
-                description: { type: 'string' },
-                medals: {
-                  type: 'object',
-                  properties: {
-                    '{medal_id}': {
+        ...response200(
+          "Provides a list of the data that's publicly known about this empire. Throws 1002.",
+          {
+            type: 'object',
+            properties: {
+              profile: {
+                type: 'object',
+                properties: {
+                  city: { type: 'string' },
+                  description: { type: 'string' },
+                  medals: profileMedalsSchema,
+                  player_name: { type: 'string' },
+                  id: { type: 'integer' },
+                  skype: { type: 'string' },
+                  name: { type: 'string' },
+                  species: { type: 'string' },
+                  country: { type: 'string' },
+                  date_founded: { type: 'string' },
+                  known_colonies: {
+                    type: 'array',
+                    items: {
                       type: 'object',
                       properties: {
-                        date: { type: 'string' },
-                        times_earned: { type: 'integer' },
-                        name: { type: 'string' },
-                        image: { type: 'string' },
-                      },
-                      required: ['date', 'times_earned', 'name', 'image'],
-                    },
-                  },
-                },
-                player_name: { type: 'string' },
-                id: { type: 'integer' },
-                skype: { type: 'string' },
-                name: { type: 'string' },
-                species: { type: 'string' },
-                country: { type: 'string' },
-                date_founded: { type: 'string' },
-                known_colonies: {
-                  type: 'array',
-                  items: {
-                    type: 'object',
-                    properties: {
-                      type: { type: 'string' },
-                      id: { type: 'integer' },
-                      star_name: { type: 'string' },
-                      ore: {
-                        type: 'object',
-                        properties: {
-                          methane: { type: 'integer' },
-                          fluorite: { type: 'integer' },
-                          beryl: { type: 'integer' },
-                          goethite: { type: 'integer' },
-                          gold: { type: 'integer' },
-                          chalcopyrite: { type: 'integer' },
-                          anthracite: { type: 'integer' },
-                          bauxite: { type: 'integer' },
-                          galena: { type: 'integer' },
-                          monazite: { type: 'integer' },
-                          trona: { type: 'integer' },
-                          halite: { type: 'integer' },
-                          uraninite: { type: 'integer' },
-                          zircon: { type: 'integer' },
-                          chromite: { type: 'integer' },
-                          kerogen: { type: 'integer' },
-                          rutile: { type: 'integer' },
-                          magnetite: { type: 'integer' },
-                          sulfur: { type: 'integer' },
-                          gypsum: { type: 'integer' },
+                        type: { type: 'string' },
+                        id: { type: 'integer' },
+                        star_name: { type: 'string' },
+                        ore: {
+                          type: 'object',
+                          properties: {
+                            methane: { type: 'integer' },
+                            fluorite: { type: 'integer' },
+                            beryl: { type: 'integer' },
+                            goethite: { type: 'integer' },
+                            gold: { type: 'integer' },
+                            chalcopyrite: { type: 'integer' },
+                            anthracite: { type: 'integer' },
+                            bauxite: { type: 'integer' },
+                            galena: { type: 'integer' },
+                            monazite: { type: 'integer' },
+                            trona: { type: 'integer' },
+                            halite: { type: 'integer' },
+                            uraninite: { type: 'integer' },
+                            zircon: { type: 'integer' },
+                            chromite: { type: 'integer' },
+                            kerogen: { type: 'integer' },
+                            rutile: { type: 'integer' },
+                            magnetite: { type: 'integer' },
+                            sulfur: { type: 'integer' },
+                            gypsum: { type: 'integer' },
+                          },
+                          required: [
+                            'methane',
+                            'fluorite',
+                            'beryl',
+                            'goethite',
+                            'gold',
+                            'chalcopyrite',
+                            'anthracite',
+                            'bauxite',
+                            'galena',
+                            'monazite',
+                            'trona',
+                            'halite',
+                            'uraninite',
+                            'zircon',
+                            'chromite',
+                            'kerogen',
+                            'rutile',
+                            'magnetite',
+                            'sulfur',
+                            'gypsum',
+                          ],
                         },
-                        required: [
-                          'methane',
-                          'fluorite',
-                          'beryl',
-                          'goethite',
-                          'gold',
-                          'chalcopyrite',
-                          'anthracite',
-                          'bauxite',
-                          'galena',
-                          'monazite',
-                          'trona',
-                          'halite',
-                          'uraninite',
-                          'zircon',
-                          'chromite',
-                          'kerogen',
-                          'rutile',
-                          'magnetite',
-                          'sulfur',
-                          'gypsum',
-                        ],
-                      },
-                      homeworld: { type: 'integer' },
-                      x: { type: 'integer' },
-                      size: { type: 'integer' },
-                      star_id: { type: 'integer' },
-                      name: { type: 'string' },
-                      empire: {
-                        type: 'object',
-                        properties: {
-                          name: { type: 'string' },
-                          is_isolationist: { type: 'integer' },
-                          id: { type: 'integer' },
-                          alignment: { type: 'string' },
+                        homeworld: { type: 'integer' },
+                        x: { type: 'integer' },
+                        size: { type: 'integer' },
+                        star_id: { type: 'integer' },
+                        name: { type: 'string' },
+                        empire: {
+                          type: 'object',
+                          properties: {
+                            name: { type: 'string' },
+                            is_isolationist: { type: 'integer' },
+                            id: { type: 'integer' },
+                            alignment: { type: 'string' },
+                          },
+                          required: ['name', 'is_isolationist', 'id', 'alignment'],
                         },
-                        required: ['name', 'is_isolationist', 'id', 'alignment'],
+                        orbit: { type: 'integer' },
+                        zone: { type: 'string' },
+                        y: { type: 'integer' },
+                        image: { type: 'string' },
+                        notes: { type: 'string' },
+                        water: { type: 'integer' },
                       },
-                      orbit: { type: 'integer' },
-                      zone: { type: 'string' },
-                      y: { type: 'integer' },
-                      image: { type: 'string' },
-                      notes: { type: 'string' },
-                      water: { type: 'integer' },
+                      required: [
+                        'type',
+                        'id',
+                        'star_name',
+                        'homeworld',
+                        'x',
+                        'size',
+                        'star_id',
+                        'name',
+                        'orbit',
+                        'zone',
+                        'y',
+                        'image',
+                        'notes',
+                        'water',
+                      ],
                     },
-                    required: [
-                      'type',
-                      'id',
-                      'star_name',
-                      'homeworld',
-                      'x',
-                      'size',
-                      'star_id',
-                      'name',
-                      'orbit',
-                      'zone',
-                      'y',
-                      'image',
-                      'notes',
-                      'water',
-                    ],
                   },
+                  status_message: { type: 'string' },
+                  last_login: { type: 'string' },
+                  colony_count: { type: 'integer' },
                 },
-                status_message: { type: 'string' },
-                last_login: { type: 'string' },
-                colony_count: { type: 'integer' },
+                required: [
+                  'city',
+                  'description',
+                  'medals',
+                  'player_name',
+                  'id',
+                  'skype',
+                  'name',
+                  'species',
+                  'country',
+                  'date_founded',
+                  'known_colonies',
+                  'status_message',
+                  'last_login',
+                  'colony_count',
+                ],
               },
-              required: [
-                'city',
-                'description',
-                'medals',
-                'player_name',
-                'id',
-                'skype',
-                'name',
-                'species',
-                'country',
-                'date_founded',
-                'known_colonies',
-                'status_message',
-                'last_login',
-                'colony_count',
-              ],
+              status: statusSchema(),
             },
-            status: statusSchema(),
-          },
-          required: ['profile', 'status'],
-        }),
+            required: ['profile', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: ['empire_id'],
-        properties: { empire_id: { type: 'number' } },
+        properties: {
+          empire_id: {
+            type: 'number',
+            description:
+              "The id of the empire for which you'd like to retrieve the public profile.",
+          },
+        },
       }),
     },
   },
@@ -567,7 +746,7 @@ export const empire = {
     post: {
       responses: {
         ...response200(
-          'Starts a password recovery process by sending an email with a recovery key.',
+          'Starts a password recovery process by sending an email with a recovery key. Identify the empire by exactly one of empire_id, empire_name, or email.',
           {
             type: 'object',
             properties: { sent: { type: 'integer', enum: [1] } },
@@ -579,11 +758,23 @@ export const empire = {
 
       ...requestBodySchema({
         type: 'object',
-        required: ['empire_id', 'empire_name', 'email'],
+        required: [],
         properties: {
-          empire_id: { type: 'number' },
-          empire_name: { type: 'string' },
-          email: { type: 'string' },
+          empire_id: {
+            type: 'number',
+            description:
+              'The unique id of the empire to recover. Choose one of empire_id, empire_name, or email.',
+          },
+          empire_name: {
+            type: 'string',
+            description:
+              'The full name of the empire. Choose one of empire_id, empire_name, or email.',
+          },
+          email: {
+            type: 'string',
+            description:
+              'The email address associated with an empire. Choose one of empire_id, empire_name, or email.',
+          },
         },
       }),
     },
@@ -607,10 +798,25 @@ export const empire = {
         type: 'object',
         required: ['reset_key', 'password1', 'password2', 'api_key'],
         properties: {
-          reset_key: { type: 'number' },
-          password1: { type: 'string' },
-          password2: { type: 'string' },
-          api_key: { type: 'string' },
+          reset_key: {
+            type: 'number',
+            description:
+              'A key that was emailed to the user via the send_password_reset_message method.',
+          },
+          password1: {
+            type: 'string',
+            description:
+              'The password to log in to the empire. Must be between 6 and 30 characters.',
+          },
+          password2: {
+            type: 'string',
+            description: 'Retyping the password again. This must match password1 to succeed.',
+          },
+          api_key: {
+            type: 'string',
+            description:
+              "Your client's unique API key, identifying it from all other clients. See ApiKeys for details.",
+          },
         },
       }),
     },
@@ -632,7 +838,17 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['password1', 'password2'],
-        properties: { password1: { type: 'string' }, password2: { type: 'string' } },
+        properties: {
+          password1: {
+            type: 'string',
+            description:
+              'The password to log in to the empire. Must be between 6 and 30 characters.',
+          },
+          password2: {
+            type: 'string',
+            description: 'Retyping the password again. This must match password1 to succeed.',
+          },
+        },
       }),
     },
   },
@@ -666,7 +882,13 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['name'],
-        properties: { name: { type: 'string' } },
+        properties: {
+          name: {
+            type: 'string',
+            description:
+              "The name you're searching for. Case insensitive, and partial names work fine. Must be at least 3 characters.",
+          },
+        },
       }),
     },
   },
@@ -686,7 +908,13 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['message'],
-        properties: { message: { type: 'string' } },
+        properties: {
+          message: {
+            type: 'string',
+            description:
+              "A message to indicate what you're doing, how you're feeling, or other status indicator. Limited to 100 characters, cannot be blank, and cannot contain @, &, <, >, or ;.",
+          },
+        },
       }),
     },
   },
@@ -696,36 +924,39 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Shows the dates boosts have expired or will expire', {
-          type: 'object',
-          properties: {
-            boosts: {
-              type: 'object',
-              properties: {
-                spy_training: { type: 'string', format: 'date-time' },
-                ore: { type: 'string', format: 'date-time' },
-                water: { type: 'string', format: 'date-time' },
-                storage: { type: 'string', format: 'date-time' },
-                food: { type: 'string', format: 'date-time' },
-                happiness: { type: 'string', format: 'date-time' },
-                building: { type: 'string', format: 'date-time' },
-                energy: { type: 'string', format: 'date-time' },
+        ...response200(
+          'Shows the dates at which boosts have expired or will expire. Boosts are subsidies applied to various resources using essentia.',
+          {
+            type: 'object',
+            properties: {
+              boosts: {
+                type: 'object',
+                properties: {
+                  spy_training: { type: 'string', format: 'date-time' },
+                  ore: { type: 'string', format: 'date-time' },
+                  water: { type: 'string', format: 'date-time' },
+                  storage: { type: 'string', format: 'date-time' },
+                  food: { type: 'string', format: 'date-time' },
+                  happiness: { type: 'string', format: 'date-time' },
+                  building: { type: 'string', format: 'date-time' },
+                  energy: { type: 'string', format: 'date-time' },
+                },
+                required: [
+                  'spy_training',
+                  'ore',
+                  'water',
+                  'storage',
+                  'food',
+                  'happiness',
+                  'building',
+                  'energy',
+                ],
               },
-              required: [
-                'spy_training',
-                'ore',
-                'water',
-                'storage',
-                'food',
-                'happiness',
-                'building',
-                'energy',
-              ],
+              status: statusSchema(),
             },
-            status: statusSchema(),
-          },
-          required: ['boosts', 'status'],
-        }),
+            required: ['boosts', 'status'],
+          }
+        ),
         ...response500(),
       },
     },
@@ -737,7 +968,7 @@ export const empire = {
 
       responses: {
         ...response200(
-          'Spends 5 essentia, and boosts storage (all 5 types) on all planets for 7 days. If a boost is already underway, calling again will add 7 more days.',
+          'Spends 5 essentia, and boosts storage (all 5 types) on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
           {
             type: 'object',
             properties: {
@@ -753,7 +984,14 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -763,21 +1001,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            food_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['food_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts food production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              food_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['food_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -787,21 +1035,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            water_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['water_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts water production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              water_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['water_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -811,21 +1069,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            energy_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['energy_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts energy production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              energy_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['energy_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -835,21 +1103,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            ore_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['ore_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts ore production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              ore_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['ore_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -859,21 +1137,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            happiness_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['happiness_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts happiness production on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              happiness_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['happiness_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -883,21 +1171,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            building_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['building_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts build queues on all planets for 7 days. If a boost is already underway, calling again will add 7 more days. It will not boost builds already under way, only new builds added to a build queue. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              building_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['building_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -907,21 +1205,31 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('', {
-          type: 'object',
-          properties: {
-            spy_training_boost: { type: 'string', format: 'date-time' },
-            status: statusSchema(),
-          },
-          required: ['spy_training_boost', 'status'],
-        }),
+        ...response200(
+          'Spends 5 essentia, and boosts spy training speed on all planets by 50% for 7 days. If a boost is already underway, calling again will add 7 more days. Unlike the other boosts, this one also boosts spies already in specialist training. Throws 1011.',
+          {
+            type: 'object',
+            properties: {
+              spy_training_boost: { type: 'string', format: 'date-time' },
+              status: statusSchema(),
+            },
+            required: ['spy_training_boost', 'status'],
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: [],
-        properties: { weeks: { type: 'integer', minimum: 1 } },
+        properties: {
+          weeks: {
+            type: 'integer',
+            minimum: 1,
+            description:
+              'Optional. The number of 7 day boost periods to buy at once, at 5 essentia each. Defaults to 1.',
+          },
+        },
       }),
     },
   },
@@ -945,7 +1253,7 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Disables the self distruction countdown.', {
+        ...response200('Disables the self destruction countdown.', {
           type: 'object',
           properties: { status: statusSchema() },
           required: ['status'],
@@ -974,7 +1282,12 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['code'],
-        properties: { code: { type: 'string' } },
+        properties: {
+          code: {
+            type: 'string',
+            description: 'A 36 character string that was sent to the user via email.',
+          },
+        },
       }),
     },
   },
@@ -985,7 +1298,7 @@ export const empire = {
 
       responses: {
         ...response200(
-          "Updates the species definition for an empire that hasn't been founded yet. Returns 1.",
+          "Updates the empire's species and returns 1. Can only be called after create and before found; calling it outside that window throws an exception. Use redefine_species for an empire that has already been founded, and see get_species_templates for ready-made starting points. Throws 1000, 1002, 1005, 1007, 1008, 1009, and 1010 — the error data names the field that needs adjusting whenever the problem can be attributed to a single field.",
           { type: 'integer', enum: [1] }
         ),
         ...response500(),
@@ -994,18 +1307,26 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['empire_id', 'params'],
-        properties: { empire_id: { type: 'string' }, params: speciesSchema() },
+        properties: {
+          empire_id: {
+            type: 'string',
+            description: 'The id of the empire you wish to update a species for.',
+          },
+          params: {
+            ...speciesSchema(),
+            description:
+              'The species definition. Every field except name and description is an integer, and those integers must add up to exactly 45.',
+          },
+        },
       }),
     },
   },
 
   '/v2/empire/redefine_species_limits': {
     post: {
-      ...security(),
-
       responses: {
         ...response200(
-          'Returns the limits that apply if the empire wants to redefine its species.',
+          'Returns the extra limits placed upon an empire that wants to redefine its species, including the essentia cost, the settable orbit range, the minimum growth affinity, and whether a redefinition is currently allowed at all.',
           {
             type: 'object',
             required: ['essentia_cost', 'max_orbit', 'min_orbit', 'min_growth', 'can', 'status'],
@@ -1030,18 +1351,23 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Redefines the species of an already-founded empire.', {
-          type: 'object',
-          required: ['status'],
-          properties: { status: statusSchema() },
-        }),
+        ...response200(
+          "Spends essentia to redefine the empire's species affinities, name, and description. Only usable after the empire has been founded — use update_species during empire creation instead. See also redefine_species_limits. WARNING: once this is done it cannot be redone for 1 month, so make sure the user is aware and prompt them appropriately before submitting.",
+          { type: 'object', required: ['status'], properties: { status: statusSchema() } }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
         required: ['params'],
-        properties: { params: speciesSchema() },
+        properties: {
+          params: {
+            ...speciesSchema(),
+            description:
+              'The species definition, same as the params of update_species. Every field except name and description is an integer, and those integers must add up to exactly 45.',
+          },
+        },
       }),
     },
   },
@@ -1051,11 +1377,14 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200("Returns the empire's original species attributes.", {
-          type: 'object',
-          required: ['species', 'status'],
-          properties: { species: speciesSchema(), status: statusSchema() },
-        }),
+        ...response200(
+          "Returns the stats associated with the empire's species as it was originally created. An empire can only view its own species stats through this method.",
+          {
+            type: 'object',
+            required: ['species', 'status'],
+            properties: { species: speciesSchema(), status: statusSchema() },
+          }
+        ),
         ...response500(),
       },
     },
@@ -1065,7 +1394,7 @@ export const empire = {
     post: {
       responses: {
         ...response200(
-          'Returns the list of pre-defined species templates available when founding an empire.',
+          'Returns the list of species templates that can be used to help the user populate the form for update_species.',
           { type: 'array', items: speciesSchema() }
         ),
         ...response500(),
@@ -1107,40 +1436,63 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Authorizes one or more empires (or an alliance) to sit for this empire.', {
-          type: 'object',
-          required: ['auths', 'status'],
-          properties: {
-            auths: {
-              type: 'array',
-              items: {
-                type: 'object',
-                required: ['id', 'name'],
-                properties: { id: { type: 'integer' }, name: { type: 'string' } },
+        ...response200(
+          'Authorizes other empires to babysit this account. Each authorization is created if needed and granted for the full server-defined period. Returns the same list as view_authorized_sitters, plus any ids that were rejected.',
+          {
+            type: 'object',
+            required: ['auths', 'status'],
+            properties: {
+              auths: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  required: ['id', 'name'],
+                  properties: { id: { type: 'integer' }, name: { type: 'string' } },
+                },
               },
-            },
-            rejected_ids: {
-              type: 'array',
-              items: {
-                type: 'object',
-                required: ['id', 'reason'],
-                properties: { id: { type: 'string' }, reason: { type: 'string' } },
+              rejected_ids: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  required: ['id', 'reason'],
+                  properties: { id: { type: 'string' }, reason: { type: 'string' } },
+                },
               },
+              status: statusSchema(),
             },
-            status: statusSchema(),
-          },
-        }),
+          }
+        ),
         ...response500(),
       },
 
       ...requestBodySchema({
         type: 'object',
+        description: 'One or more of the following options.',
         properties: {
-          allied: { type: 'integer', enum: [1, 0] },
-          alliance: { type: 'string' },
-          alliance_id: { type: 'string' },
-          empires: { type: 'array', items: { type: 'string' } },
-          revalidate_all: { type: 'integer', enum: [1, 0] },
+          allied: {
+            type: 'integer',
+            enum: [1, 0],
+            description: 'If true, all allies are automatically selected.',
+          },
+          alliance: {
+            type: 'string',
+            description: 'The name of another alliance, all of whom are automatically selected.',
+          },
+          alliance_id: {
+            type: 'string',
+            description: 'The id of another alliance, all of whom are automatically selected.',
+          },
+          empires: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'The ids and/or names of specific empires being authorized.',
+          },
+          revalidate_all: {
+            type: 'integer',
+            enum: [1, 0],
+            description:
+              'A quick way of selecting all currently-authorized empires in order to extend their authorization period.',
+          },
         },
       }),
     },
@@ -1151,7 +1503,7 @@ export const empire = {
       ...security(),
 
       responses: {
-        ...response200('Removes sitting authorization from one or more empires.', {
+        ...response200('Removes sitters from being permitted to sit this account.', {
           type: 'object',
           required: ['status'],
           properties: { status: statusSchema() },
@@ -1162,7 +1514,13 @@ export const empire = {
       ...requestBodySchema({
         type: 'object',
         required: ['empires'],
-        properties: { empires: { type: 'array', items: { type: 'string' } } },
+        properties: {
+          empires: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'The ids (not names) of specific empires being removed.',
+          },
+        },
       }),
     },
   },
diff --git a/src/spec/paths/map.ts b/src/spec/paths/map.ts
index b76d46d..0d37edf 100644
--- a/src/spec/paths/map.ts
+++ b/src/spec/paths/map.ts
@@ -324,11 +324,11 @@ export const map = {
               type: 'array',
               items: {
                 type: 'object',
-                required: ['id', 'name', 'description', 'date_enacted'],
+                required: ['id', 'name', 'descripition', 'date_enacted'],
                 properties: {
                   id: { type: 'string' },
                   name: { type: 'string' },
-                  description: { type: 'string' },
+                  descripition: { type: 'string' },
                   date_enacted: { type: 'string' },
                 },
               },