{
 "openapi": "3.1.0",
 "info": {
  "title": "CourseToJob API",
  "version": "1.0.0",
  "description": "Free, anonymous, read-only access to CourseToJob's careers, degree subjects and country data (ILO, OECD, World Bank, US BLS, UK DfE LEO, ESCO), plus an MCP server and an A2A agent. Responses are CC BY 4.0: please cite CourseToJob and the original source.",
  "contact": {
   "email": "hello@elitedigitalagency.io",
   "url": "https://coursetojob.com/contact/"
  },
  "license": {
   "name": "CC BY 4.0",
   "url": "https://creativecommons.org/licenses/by/4.0/"
  },
  "x-updated": "2026-09-26"
 },
 "servers": [
  {
   "url": "https://coursetojob.com"
  }
 ],
 "externalDocs": {
  "url": "https://coursetojob.com/data/",
  "description": "Human-readable API, MCP and dataset documentation"
 },
 "paths": {
  "/api/v1/index.json": {
   "get": {
    "operationId": "apiIndex",
    "summary": "API catalogue and endpoint templates",
    "responses": {
     "200": {
      "description": "API index",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/search": {
   "get": {
    "operationId": "search",
    "summary": "Search careers, subjects, countries and guides in 12 languages",
    "parameters": [
     {
      "name": "q",
      "in": "query",
      "required": true,
      "schema": {
       "type": "string"
      }
     },
     {
      "name": "lang",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "en",
        "es",
        "pt",
        "fr",
        "de",
        "it",
        "ar",
        "zh",
        "ja",
        "ko",
        "hi",
        "id"
       ]
      }
     },
     {
      "name": "type",
      "in": "query",
      "schema": {
       "type": "string",
       "enum": [
        "career",
        "subject",
        "country",
        "guide"
       ]
      }
     },
     {
      "name": "limit",
      "in": "query",
      "schema": {
       "type": "integer",
       "minimum": 1,
       "maximum": 25
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Ranked results",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/careers.json": {
   "get": {
    "operationId": "listCareers",
    "summary": "All careers with codes, names in 12 languages and US median pay",
    "responses": {
     "200": {
      "description": "Career list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/careers/{id}.json": {
   "get": {
    "operationId": "getCareer",
    "summary": "Full career record: text in 12 languages, BLS pay, ILO group earnings, ESCO skills",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Career id, e.g. software-developer",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Career",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Unknown id"
     }
    }
   }
  },
  "/api/v1/subjects.json": {
   "get": {
    "operationId": "listSubjects",
    "summary": "All degree subjects",
    "responses": {
     "200": {
      "description": "Subject list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/subjects/{id}.json": {
   "get": {
    "operationId": "getSubject",
    "summary": "Full subject record: careers, OECD outcomes by field, UK LEO earnings, text in 12 languages",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "description": "Subject id, e.g. computer-science",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Subject",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Unknown id"
     }
    }
   }
  },
  "/api/v1/countries.json": {
   "get": {
    "operationId": "listCountries",
    "summary": "All countries with headline graduate metrics",
    "responses": {
     "200": {
      "description": "Country list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/api/v1/countries/{iso2}.json": {
   "get": {
    "operationId": "getCountry",
    "summary": "Full ILO, OECD and World Bank data for one country",
    "parameters": [
     {
      "name": "iso2",
      "in": "path",
      "required": true,
      "description": "Lower-case ISO 3166-1 alpha-2 code, e.g. de",
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Country",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     },
     "404": {
      "description": "Unknown code"
     }
    }
   }
  },
  "/api/v1/guides.json": {
   "get": {
    "operationId": "listGuides",
    "summary": "Guides with titles in 12 languages",
    "responses": {
     "200": {
      "description": "Guide list",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/data/graduate-outcomes-by-country.csv": {
   "get": {
    "operationId": "outcomesCsv",
    "summary": "Graduate outcomes by country (CSV)",
    "responses": {
     "200": {
      "description": "CSV",
      "content": {
       "text/csv": {
        "schema": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  },
  "/data/datapackage.json": {
   "get": {
    "operationId": "dataPackage",
    "summary": "Frictionless Data Package descriptor",
    "responses": {
     "200": {
      "description": "Data package",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/mcp": {
   "post": {
    "operationId": "mcp",
    "summary": "MCP server (JSON-RPC 2.0, streamable HTTP, stateless). Methods: initialize, ping, tools/list, tools/call, resources/list, resources/read, prompts/list.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "JSON-RPC response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   },
   "get": {
    "operationId": "mcpInfo",
    "summary": "MCP discovery document",
    "responses": {
     "200": {
      "description": "Server info",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  },
  "/a2a": {
   "post": {
    "operationId": "a2a",
    "summary": "A2A agent (JSON-RPC 2.0, message/send)",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object"
       }
      }
     }
    },
    "responses": {
     "200": {
      "description": "A2A response",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   },
   "get": {
    "operationId": "a2aInfo",
    "summary": "A2A discovery document",
    "responses": {
     "200": {
      "description": "Agent info",
      "content": {
       "application/json": {
        "schema": {
         "type": "object"
        }
       }
      }
     }
    }
   }
  }
 }
}