{ "openapi": "3.1.0", "info": { "title": "Youth4work agent API", "version": "2.3.2", "description": "Act on a Youth4work account (India's talent platform) for its owner. Job seekers: complete the profile, find and apply to jobs, take skill tests, answer WorkMail. Employers: post jobs, review applicants, find and contact matching candidates, send WorkMail, run assessments. The same tools as the MCP server https://mcp.youth4work.com/mcp. Sign-in: OAuth 2.1 (authorization code + PKCE, dynamic client registration), or agent registration per https://www.youth4work.com/auth.md.", "contact": { "name": "Youth4work", "url": "https://mcp.youth4work.com/docs", "email": "support@youth4work.com" }, "termsOfService": "https://mcp.youth4work.com/terms" }, "externalDocs": { "url": "https://mcp.youth4work.com/docs" }, "servers": [ { "url": "https://mcp.youth4work.com" } ], "security": [ { "oauth2": [ "youth4work" ] } ], "tags": [ { "name": "seeker", "description": "Job seeker accounts" }, { "name": "employer", "description": "Employer / recruiter accounts" }, { "name": "public", "description": "Public read-only data, no sign-in" } ], "paths": { "/mcp/api/v1/tools/get_me": { "post": { "operationId": "get_me", "summary": "Who am I", "description": "The connected Youth4work account: role (job_seeker or employer), name, username, profile or company summary, nextSteps (what to complete or do next) and links to the user's dashboard pages on youth4work.com. Call this first.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_my_next_steps": { "post": { "operationId": "get_my_next_steps", "summary": "My next steps", "description": "A step-by-step plan for this job seeker: 1) what the profile still lacks (photo, headline, about, skills, education, experience, CV, e-mail/mobile verification, city, ...; each with the tool that fixes it) and the completeness %, 2) the best matching live jobs not applied to yet, 3) free skill tests (yTest) and popular mock tests they have not taken, with start links. Read-only. Use it at the start of a session and after finishing a step.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_workmail": { "post": { "operationId": "list_workmail", "summary": "List WorkMail conversations", "description": "The user's Youth4work WorkMail (inbox) conversations, newest first: the other person (name, username, job seeker or employer, profile url), the last message snippet and who sent it, date and unread count, plus the total unread. No e-mail addresses. Use read_workmail_thread to open one.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 }, "unread_only": { "description": "Only conversations with unread messages", "type": "boolean" } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/read_workmail_thread": { "post": { "operationId": "read_workmail_thread", "summary": "Read a WorkMail conversation", "description": "One WorkMail conversation with a member, oldest to newest (page 1 = the latest 30 messages; page 2 = older): who wrote each message, the text and the date. Opening it marks their messages as read, as on the site.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 100, "description": "The other person's username (from list_workmail)" }, "page": { "description": "1 = latest messages (default), 2+ = older", "type": "integer", "minimum": 1, "maximum": 100 } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/send_workmail": { "post": { "operationId": "send_workmail", "summary": "Send WorkMail", "description": "Send a WorkMail to one member (one recipient per call, 30 a day; the site also limits how many NEW conversations a job seeker can start per day). Draft it in the user's voice, show it, and send only after they approve. If you already have a conversation with the person it is added as a reply, otherwise a new conversation starts (private profiles can only be replied to). The message is stored in both inboxes and e-mailed to the recipient like on the site. Plain text, max 4000 characters; obvious spam is refused. Returns per-recipient results.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "minItems": 1, "maxItems": 1, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } } ], "description": "The recipient's username" }, "subject": { "description": "Short subject (used as the e-mail subject and the first line of the message)", "type": "string", "maxLength": 150 }, "message": { "type": "string", "minLength": 1, "maxLength": 4000, "description": "The message, plain text" } }, "required": [ "to", "message" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/upload_photo": { "post": { "operationId": "upload_photo", "summary": "Upload my profile photo or banner", "description": "Set the user's profile photo (kind \"profile\": centre-cropped to a square, at least 100x100 px) or the wide banner at the top of their profile (kind \"banner\": centre-cropped to about 3.6:1, at least 600x150 px). Give EITHER image_url (direct https link to the image) OR image_base64. JPEG, PNG, GIF, BMP, WebP or HEIC under 5 MB; the image is checked and re-encoded. Replaces the current one. Limit 20 image uploads a day. Only use a photo the user gave you for this, and for a profile photo it should be a clear photo of the user.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "profile", "banner" ], "description": "profile or banner" }, "image_url": { "description": "Direct https link to the image file (not a web page or a share page that needs a login)", "type": "string", "maxLength": 2000, "format": "uri" }, "image_base64": { "description": "The image file's bytes, base64-encoded (a data: URL is fine)", "type": "string", "maxLength": 7200000 } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/set_social_links": { "post": { "operationId": "set_social_links", "summary": "Set social links", "description": "Add, change or remove the user's social and web profile links (LinkedIn, GitHub, X/Twitter, Facebook, Instagram, YouTube, Behance, Dribbble, Medium, Stack Overflow, Kaggle, LeetCode, own website/portfolio). They are shown publicly on the profile page /y/{username} (nofollow). Only the networks you pass change; null or \"\" removes one. Give a full https link, or just the handle for networks with simple profile URLs (e.g. github: \"octocat\", twitter: \"@octocat\"). Each link is checked to be on that network's domain and to be a personal profile page (e.g. LinkedIn /in/...); share, login and search links are refused. Only add links the user confirmed are theirs. Returns the saved links. get_my_profile shows the current ones.\n\nFor: job seekers and employers.", "tags": [ "seeker", "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "links": { "type": "object", "properties": { "linkedin": { "description": "linkedin profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "github": { "description": "github profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "twitter": { "description": "twitter profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "facebook": { "description": "facebook profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "instagram": { "description": "instagram profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "youtube": { "description": "youtube profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "behance": { "description": "behance profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "dribbble": { "description": "dribbble profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "medium": { "description": "medium profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "stackoverflow": { "description": "stackoverflow profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "kaggle": { "description": "kaggle profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "leetcode": { "description": "leetcode profile link or handle", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] }, "website": { "description": "Own website, portfolio or blog (any public https link)", "anyOf": [ { "type": "string", "maxLength": 300 }, { "type": "null" } ] } }, "description": "e.g. {\"linkedin\": \"https://www.linkedin.com/in/priya-sharma\", \"github\": \"priyasharma\", \"twitter\": null}" } }, "required": [ "links" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_my_profile": { "post": { "operationId": "get_my_profile", "summary": "Get my profile", "description": "The signed-in job seeker's own full profile, every section of the site's Edit Profile page, including private fields: name, e-mail, mobile, city, preferred locations, headline, about, career aim, looking-for flags and dates, skills (with yTest score and test link), education, class 10/12 schools, experience, projects and documents (each with the id needed to edit or delete it), personal info (gender, date of birth, address, PIN, alternate e-mail/mobile, verified flags), salary details, extracurricular activities, video resume link, social links, account settings, CV url, profile url, completeness % and `missing` (what to add next, with the tool to use). Call this before editing the profile. Private fields are for the user only: never repeat them to anyone else.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/update_profile": { "post": { "operationId": "update_profile", "summary": "Update my profile", "description": "Change any of: name, headline, about, career aim, city, preferred job locations, what they are looking for (with availability dates), extracurricular activities, video resume link, salary details (current / expected CTC and experience). Only the fields you pass change; everything else stays. Plain text only (no HTML). Cities must be Indian city names as Youth4work lists them (the error suggests close names). A new headline or about text may be held for moderator review (the result's notes say so). Show the user the new text and get their OK first; never invent facts. Returns the updated profile. Contact details, gender and date of birth are in update_personal_info.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "first_name": { "description": "First name (letters only)", "type": "string", "minLength": 1, "maxLength": 60 }, "last_name": { "description": "Last name (letters only)", "type": "string", "minLength": 1, "maxLength": 60 }, "headline": { "description": "One-line professional headline, e.g. \"B.Tech CSE 2025 | Python, SQL | Seeking data analyst roles\". \"\" clears it.", "type": "string", "maxLength": 150 }, "about": { "description": "About summary, max 500 characters. \"\" clears it.", "type": "string", "maxLength": 500 }, "career_aim": { "description": "Career aim / objective, max 500 characters. \"\" clears it.", "type": "string", "maxLength": 500 }, "city": { "description": "Current city, e.g. \"Pune\"", "type": "string", "minLength": 2, "maxLength": 50 }, "preferred_locations": { "description": "Cities where they want to work (replaces the list; [] clears it)", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 50 } }, "looking_for": { "description": "What they are looking for; flags and dates not given stay as they are. Dates are kept only while the matching flag is on.", "type": "object", "properties": { "full_time": { "type": "boolean" }, "part_time": { "type": "boolean" }, "internship": { "type": "boolean" }, "full_time_from": { "description": "Available for full-time jobs from (YYYY-MM); \"\" clears", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{1,2}$" }, { "type": "string", "const": "" } ] }, "internship_from": { "description": "Internship wanted from (YYYY-MM); \"\" clears", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{1,2}$" }, { "type": "string", "const": "" } ] }, "internship_to": { "description": "Internship wanted until (YYYY-MM); \"\" clears", "anyOf": [ { "type": "string", "pattern": "^\\d{4}-\\d{1,2}$" }, { "type": "string", "const": "" } ] } } }, "extracurricular_activities": { "description": "Replaces the list, e.g. [\"Chess\", \"NSS volunteer\", \"College football team\"]; [] clears it", "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 60 } }, "video_resume_url": { "description": "https link to a video introduction (YouTube, Vimeo, Drive...), max 100 characters (use the short youtu.be link); \"\" removes it", "type": "string", "maxLength": 200 }, "salary_details": { "description": "Salary and experience as recruiters see them on the profile; fields not given stay", "type": "object", "properties": { "current_ctc_lakhs": { "description": "Current annual CTC in lakh rupees, e.g. 3.5 (0 for freshers)", "type": "number", "minimum": 0, "maximum": 59.99 }, "expected_ctc_lakhs": { "description": "Expected annual CTC in lakh rupees", "type": "number", "minimum": 0, "maximum": 59.99 }, "total_experience_months": { "type": "integer", "minimum": 0, "maximum": 600 }, "relevant_experience_months": { "type": "integer", "minimum": 0, "maximum": 600 } } } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/update_personal_info": { "post": { "operationId": "update_personal_info", "summary": "Update my personal information", "description": "Change the private personal details of the profile: login e-mail, alternate e-mail, mobile, alternate mobile, gender, date of birth, address, PIN code (the site's Personal Information section; Aadhaar is not available here). Only the fields you pass change. These are never shown publicly; recruiters see contact details only when the user applies or they unlock the profile. Changing the e-mail changes the LOGIN and makes it unverified (the user re-verifies via the link in the result); a new mobile is also unverified. Use only details the user gave you, and confirm an e-mail or mobile change with them first. An e-mail or mobile already used by another account is refused. Limit 10 changes a day. Returns the updated profile.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "description": "New login e-mail", "type": "string", "maxLength": 100, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "alternate_email": { "description": "Second e-mail; \"\" clears it", "type": "string", "maxLength": 100 }, "mobile": { "description": "10-digit Indian mobile, +91 optional", "type": "string", "maxLength": 16 }, "alternate_mobile": { "description": "Second mobile; \"\" clears it", "type": "string", "maxLength": 16 }, "gender": { "type": "string", "enum": [ "male", "female", "other" ] }, "date_of_birth": { "description": "YYYY-MM-DD; \"\" clears it", "type": "string", "pattern": "^(\\d{4}-\\d{2}-\\d{2})?$" }, "address": { "description": "Current address; \"\" clears it", "type": "string", "maxLength": 200 }, "pincode": { "description": "6-digit PIN code; \"\" clears it", "type": "string", "maxLength": 10 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/update_settings": { "post": { "operationId": "update_settings", "summary": "Update my account settings", "description": "Change the account settings of the site's Settings section: profile_private (true hides the profile from recruiter searches and public pages), email_notifications (false unsubscribes from ALL Youth4work notification e-mails, including job alerts and WorkMail alerts), auto_apply (let Youth4work apply automatically to matching jobs). Only the settings you pass change. Deactivating the account is not possible here (send the user to the settings page in the result). Explain the effect and confirm with the user first. Returns the new settings.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "profile_private": { "type": "boolean" }, "email_notifications": { "type": "boolean" }, "auto_apply": { "type": "boolean" } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/set_skills": { "post": { "operationId": "set_skills", "summary": "Set my skills", "description": "Replace the profile's skills (talents) with this full list (3 to 30; recruiters search by skill). Names are matched to Youth4work's skill list; unknown names return an error with suggestions (or pass allow_new=true to add them as new skills). Returns the saved skills, each with a yTest link the user can open to get a ranked score. Include the skills they already have that should stay (get_my_profile).\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skills": { "minItems": 3, "maxItems": 30, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 50 }, "description": "One skill per item, e.g. [\"Python\", \"SQL\", \"Data Analysis\", \"MS Excel\"]" }, "allow_new": { "description": "Add names that are not in Youth4work's list as new skills (default false)", "type": "boolean" } }, "required": [ "skills" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/save_education": { "post": { "operationId": "save_education", "summary": "Add or edit education", "description": "Add an education entry, or update one by id (ids from get_my_profile). College and course are matched to Youth4work's lists (colleges are listed like \"DU-Delhi University\"); if not found, the error lists close matches: retry with the exact name, or allow_new=true to add it. University is filled from the college when known. Returns the education list.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Education id to update; omit to add a new entry", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "college": { "type": "string", "minLength": 2, "maxLength": 200 }, "university": { "description": "Needed only when the college is not in the list", "type": "string", "maxLength": 200 }, "course": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Degree, e.g. \"B.Tech\", \"MBA\", \"B.Com\", \"12th\"" }, "specialization": { "description": "e.g. \"Computer Science\" (default \"Other\")", "type": "string", "maxLength": 200 }, "batch_from": { "type": "integer", "minimum": 1950, "maximum": 2040, "description": "Start year" }, "batch_to": { "type": "integer", "minimum": 1950, "maximum": 2040, "description": "End (or expected end) year" }, "score": { "description": "Percentage score; under 30 or omitted is stored hidden", "type": "integer", "minimum": 0, "maximum": 100 }, "hide_score": { "type": "boolean" }, "is_current": { "description": "True if they are studying this now", "type": "boolean" }, "achievements": { "type": "string", "maxLength": 500 }, "allow_new": { "description": "Add a college/course that is not in the list (default false)", "type": "boolean" } }, "required": [ "college", "course", "batch_from", "batch_to" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_education": { "post": { "operationId": "delete_education", "summary": "Delete education", "description": "Delete one education entry by id (from get_my_profile). The current education cannot be deleted (mark another one current first). Confirm with the user first.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/save_school": { "post": { "operationId": "save_school", "summary": "Add or edit schooling", "description": "Add the class 10 or class 12 entry of the profile, or update one by id (from get_my_profile; one entry per class, and the class of an entry cannot change). Give exactly one of percentage, grade or cgpa. College degrees go in save_education. Returns the school list.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "School entry id to update; omit to add", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "class": { "anyOf": [ { "type": "number", "const": 10 }, { "type": "number", "const": 12 } ], "description": "10 or 12" }, "school": { "type": "string", "minLength": 2, "maxLength": 200, "description": "School name" }, "board": { "type": "string", "enum": [ "cbse", "icse", "state" ] }, "state": { "description": "State of the board, required when board is \"state\", e.g. \"Maharashtra\"", "type": "string", "maxLength": 60 }, "stream": { "description": "Mainly for class 12", "type": "string", "enum": [ "arts", "commerce", "science" ] }, "pass_out_year": { "type": "integer", "minimum": 1950, "maximum": 2040, "description": "Year of passing" }, "percentage": { "type": "number", "exclusiveMinimum": 0, "maximum": 100 }, "grade": { "type": "string", "enum": [ "A+", "A", "B+", "B", "C+", "C", "D+", "D" ] }, "cgpa": { "type": "number", "exclusiveMinimum": 0, "maximum": 10 }, "cgpa_out_of": { "description": "Scale of cgpa (default 10)", "anyOf": [ { "type": "number", "const": 5 }, { "type": "number", "const": 10 } ] }, "hide_marks": { "description": "Hide the marks on the public profile", "type": "boolean" } }, "required": [ "class", "school", "board", "pass_out_year" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_school": { "post": { "operationId": "delete_school", "summary": "Delete schooling entry", "description": "Delete the class 10 or 12 entry by id (from get_my_profile). Confirm with the user first.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/save_project": { "post": { "operationId": "save_project", "summary": "Add or edit a project", "description": "Add a project to the profile (college, internship, job or personal), or update one by id (from get_my_profile). Optionally link it to an experience_id or education_id from get_my_profile (shown as \"done at\"). Dates as YYYY-MM; give `to` or is_current=true. url: a public link to the project (GitHub repo, live site...). Plain text, never invent projects. Returns the project list.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Project id to update; omit to add", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "description": "What it does, their role, tools used (max 1000 characters)", "type": "string", "maxLength": 1000 }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{1,2}$", "description": "Start month, YYYY-MM" }, "to": { "description": "End month, YYYY-MM (omit when is_current)", "type": "string", "pattern": "^\\d{4}-\\d{1,2}$" }, "is_current": { "type": "boolean" }, "url": { "description": "Project link (http/https)", "type": "string", "maxLength": 500 }, "experience_id": { "description": "Done during this job/internship (id from get_my_profile)", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "education_id": { "description": "Done during this course (id from get_my_profile)", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "name", "from" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_project": { "post": { "operationId": "delete_project", "summary": "Delete a project", "description": "Delete one project by id (from get_my_profile). Confirm with the user first.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/upload_document": { "post": { "operationId": "upload_document", "summary": "Upload a document", "description": "Add a document to the user's yDocs (marksheets, certificates, ID), or replace the file or title of one by id (from get_my_profile). Documents are PRIVATE: only the user and Youth4work admins can open them. Give EITHER file_url (a direct public https link) OR content_base64 + file_name; PDF, Word, text or an image (JPEG/PNG/WebP/HEIC, re-encoded as PNG), under 5 MB. Use only files the user gave you for this. Limit 10 uploads a day. Returns the document list.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Document id to replace; omit to add", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "type": { "type": "string", "enum": [ "marksheet_10", "marksheet_12", "marksheet_graduation", "marksheet_post_graduation", "certificate_10", "certificate_12", "certificate_graduation", "certificate_post_graduation", "marksheet_other", "certificate_other" ], "description": "certificate_other for course / skill certificates (e.g. AWS, Coursera)" }, "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "e.g. \"Class 12 marksheet\", \"Google Data Analytics certificate\"" }, "file_url": { "description": "Direct https link to the file", "type": "string", "maxLength": 2000, "format": "uri" }, "content_base64": { "description": "The file's bytes, base64-encoded", "type": "string", "maxLength": 7200000 }, "file_name": { "description": "File name with extension (required with content_base64), e.g. \"marksheet-12.pdf\"", "type": "string", "maxLength": 200 } }, "required": [ "type", "title" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_document": { "post": { "operationId": "delete_document", "summary": "Delete a document", "description": "Delete one yDocs document by id (from get_my_profile); the stored file is removed too. Confirm with the user first.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/save_experience": { "post": { "operationId": "save_experience", "summary": "Add or edit work experience", "description": "Add a job or internship to the profile, or update one by id (from get_my_profile). Dates as YYYY-MM; give `to` or is_current=true. Full-time jobs may not overlap each other. Plain text, never invent experience. Returns the experience list.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Experience id to update; omit to add", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "job_title": { "type": "string", "minLength": 1, "maxLength": 100 }, "company": { "type": "string", "minLength": 1, "maxLength": 100 }, "job_type": { "type": "string", "enum": [ "full", "part", "intern" ], "description": "full = full-time, part = part-time, intern = internship" }, "from": { "type": "string", "pattern": "^\\d{4}-\\d{1,2}$", "description": "Start month, YYYY-MM" }, "to": { "description": "End month, YYYY-MM (omit when is_current)", "type": "string", "pattern": "^\\d{4}-\\d{1,2}$" }, "is_current": { "description": "True if they work here now", "type": "boolean" }, "responsibilities": { "type": "string", "maxLength": 1000 }, "achievements": { "type": "string", "maxLength": 1000 } }, "required": [ "job_title", "company", "job_type", "from" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_experience": { "post": { "operationId": "delete_experience", "summary": "Delete work experience", "description": "Delete one work experience entry by id (from get_my_profile). Confirm with the user first.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/upload_resume": { "post": { "operationId": "upload_resume", "summary": "Upload my CV", "description": "Put the user's CV on their profile (replaces the current one; recruiters can download it). Give EITHER file_url (a direct public https link to the file; share pages that need a login do not work) OR content_base64 + file_name. PDF, DOC, DOCX or TXT, under 5 MB; the content is checked. Up to 10 uploads a day. If you cannot pass the file, ask the user to upload it at the editProfile link from get_me.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "file_url": { "description": "Direct https link to the CV file", "type": "string", "maxLength": 2000, "format": "uri" }, "content_base64": { "description": "The file's bytes, base64-encoded", "type": "string", "maxLength": 7200000 }, "file_name": { "description": "File name with extension, e.g. \"Priya-Sharma-CV.pdf\" (required with content_base64)", "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/recommend_jobs": { "post": { "operationId": "recommend_jobs", "summary": "Recommended jobs", "description": "Live jobs that match the profile (shared skills, course, city or preferred locations), best first, each with matchReasons, job id, url and whether the user already applied. Use get_job for the full description before suggesting an application.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 25 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/apply_job": { "post": { "operationId": "apply_job", "summary": "Apply to a job", "description": "Apply to one live job for the user (the employer sees their profile and CV and gets an e-mail; the user gets a confirmation e-mail). Only after the user has seen the job (get_job) and said yes; never in bulk without their say-so. Fails if the job is not live or they already applied. Up to 25 applications a day. Returns a confirmation and the job url.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id from recommend_jobs, search_jobs or get_job" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_my_applications": { "post": { "operationId": "list_my_applications", "summary": "My job applications", "description": "Jobs the user has applied to, newest first: title, company, city, applied date, whether the job is still live, job url.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 100 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/recommend_skill_tests": { "post": { "operationId": "recommend_skill_tests", "summary": "Recommend skill tests", "description": "Free Youth4work skill tests (yTest) worth taking: for one skill if `skill` is given, otherwise for the profile's skills, the skills that matching live jobs ask for, and Aptitude. Each has the user's current score and rank if already tested, and startUrl. The USER takes the test in their own browser (give them the link); never take a test for them. A tested score ranks the profile higher for recruiters.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "description": "A skill to find tests for, e.g. \"Python\"", "type": "string", "minLength": 1, "maxLength": 50 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_my_skill_scores": { "post": { "operationId": "get_my_skill_scores", "summary": "My skill test scores", "description": "The user's tested skills: yTest score (out of 100), rank N of M among everyone with that skill, top X%, and a retake link.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/find_people_i_may_know": { "post": { "operationId": "find_people_i_may_know", "summary": "People I may know", "description": "Youth4work members the user may know: college mates (same college, same course and nearby batch first), colleagues (same company in their work experience) or people in their city with the same skills. Omit kind for a mix. Public profiles only: name, username, headline, city, why they match and the profile url (never e-mail or phone). To connect, draft a short personal note, get the user's OK, then send_workmail.\n\nFor: job seekers.", "tags": [ "seeker" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "description": "college mates, company colleagues, or same city + skills; omit for all", "type": "string", "enum": [ "college", "company", "city_skill" ] }, "page": { "description": "Result page (default 1)", "type": "integer", "minimum": 1, "maximum": 10 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/search_talent": { "post": { "operationId": "search_talent", "summary": "Search talent", "description": "Find people on Youth4work who hold a skill, ranked by their assessed talent score, optionally in one Indian city. Returns public profile cards (name, headline, city, college, course, score, profile url); never contact details. Private and deactivated profiles are excluded.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "skill": { "type": "string", "minLength": 1, "maxLength": 100, "description": "One skill or talent, e.g. \"Python\", \"Digital Marketing\", \"Aptitude\"" }, "city": { "description": "Indian city name, e.g. \"Pune\"", "type": "string", "maxLength": 100 }, "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 } }, "required": [ "skill" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/get_profile": { "post": { "operationId": "get_profile", "summary": "Get public profile", "description": "Public profile of one Youth4work member by username (the part after /y/ in https://www.youth4work.com/y/{username}): a short factual summary (the same \"About\" text the profile page shows), skill test ranks (rank N of M, top X%), headline, about, city, education, top assessed talents with scores, work experience and the canonical profile url. No contact details.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Youth4work username" } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/list_talent_categories": { "post": { "operationId": "list_talent_categories", "summary": "List talent categories", "description": "Talent categories on Youth4work (e.g. Software and Programming, Finance, Sales and Marketing) with their most popular skills. Use the skill names with search_talent.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/search_jobs": { "post": { "operationId": "search_jobs", "summary": "Search jobs", "description": "Live job and internship openings on Youth4work (www.cos.youth4work.com), newest first. Matches the keyword against job title, summary and required skills. Returns title, company, city, type, experience, salary (lakhs per year) and the job url where the user can apply.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "description": "Keyword or skill, e.g. \"python\", \"sales\"", "type": "string", "maxLength": 100 }, "city": { "description": "Indian city, e.g. \"Bangalore\"", "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "full-time", "part-time", "internship", "work-from-home" ] }, "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/get_job": { "post": { "operationId": "get_job", "summary": "Get job", "description": "Full details of one live job by id (from search_jobs): description, skills, courses, salary, experience, company page and the apply url. Recruiter contact details are not shared.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/search_mock_tests": { "post": { "operationId": "search_mock_tests", "summary": "Search mock tests", "description": "Free exam preparation on Youth4work Prep: finds exams (e.g. \"SSC CGL\", \"IBPS PO\", \"RRB NTPC\", \"CAT\") by name and/or category (e.g. \"Government Jobs\", \"Bank\", \"Placement Papers\"), most popular first, each with its exam page url and up to 5 mock tests (questions, minutes, url).\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "exam": { "description": "Exam name or part of it, e.g. \"SSC\", \"IBPS PO\"", "type": "string", "maxLength": 100 }, "category": { "description": "Category, e.g. \"Government Jobs\"", "type": "string", "maxLength": 100 }, "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/get_mock_test": { "post": { "operationId": "get_mock_test", "summary": "Get mock test", "description": "Details of one mock test by id (from search_mock_tests): exam, sections, number of questions, duration, marking, the instructions page url and the url that starts the test (free, needs a Youth4work sign-in).\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "mock_test_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Mock test id" } }, "required": [ "mock_test_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/search_colleges": { "post": { "operationId": "search_colleges", "summary": "Search colleges", "description": "Indian colleges and universities on Youth4work University. Give at least one of: name (part of the college name), course (e.g. \"B.Tech\", \"MBA\", \"B.Com\") and city (e.g. \"Pune\"). Most active on Youth4work first. Returns name, university, city, state, website and profile url.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "description": "Part of the college name", "type": "string", "maxLength": 100 }, "course": { "description": "Course offered, e.g. \"B.Tech\", \"MBA\"", "type": "string", "maxLength": 100 }, "city": { "description": "City name", "type": "string", "maxLength": 100 }, "page": { "description": "Result page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/api/v1/public/tools/get_college": { "post": { "operationId": "get_college", "summary": "Get college", "description": "Public profile of one college by id (from search_colleges): university, city, address, website, about, highlights, courses offered with fees where known, student and faculty counts, profile url.\n\nFor: Anyone (no sign-in).", "tags": [ "public" ], "security": [], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "college_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "College id" } }, "required": [ "college_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/upload_company_image": { "post": { "operationId": "upload_company_image", "summary": "Upload company logo or banner", "description": "Set the company logo (kind \"logo\": kept whole, fitted in a square) or the wide banner at the top of the company page (kind \"banner\": centre-cropped to about 3.6:1, at least 600x150 px). Give EITHER image_url (direct https link to the image) OR image_base64. JPEG, PNG, GIF, BMP, WebP or HEIC under 5 MB; the image is checked and re-encoded. Replaces the current one. Limit 20 image uploads a day. Use only images the employer gave you or approved.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "logo", "banner" ], "description": "logo or banner" }, "image_url": { "description": "Direct https link to the image file (not a web page or a share page that needs a login)", "type": "string", "maxLength": 2000, "format": "uri" }, "image_base64": { "description": "The image file's bytes, base64-encoded (a data: URL is fine)", "type": "string", "maxLength": 7200000 } }, "required": [ "kind" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_company": { "post": { "operationId": "get_company", "summary": "Get my company profile", "description": "The connected employer's company profile, every section of the site's company edit page: name, type (company / consultant / individual_recruiter), about, key highlights, why work for us, what we look for, website, size, annual turnover, industries, city, office locations (each with the id for save_company_location / delete_company_location), company representative (name, designation, e-mail, mobile, landline), social links, logo/banner urls, live job count, the public company page url and editUrl. Call before update_company.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/update_company": { "post": { "operationId": "update_company", "summary": "Update company profile", "description": "Change any subset of the company profile; fields left out stay as they are. Plain text only (HTML is removed); spammy text (phone-number ads, loan/betting/helpline content) is rejected. The company name cannot be changed here (only Youth4work support can rename a company, because it is part of every job URL). industry ADDS an industry to the list, remove_industries removes some. city sets the primary office city (address optional); other offices: save_company_location. representative is the company's contact person (fields not given stay). Returns the updated profile. Limit 20 updates a day.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "about": { "description": "About the company (max 2000 characters)", "type": "string", "maxLength": 2000 }, "key_highlights": { "description": "Short summary / key highlights shown at the top of the company page (max 500)", "type": "string", "maxLength": 500 }, "why_work_for_us": { "description": "Why work for us (max 2000)", "type": "string", "maxLength": 2000 }, "what_we_look_for": { "description": "What we look for in candidates (max 2000)", "type": "string", "maxLength": 2000 }, "website": { "description": "Company website, e.g. https://www.example.com", "type": "string", "maxLength": 200 }, "industry": { "description": "Industry to add, e.g. \"Information Technology\", \"Education\"", "type": "string", "maxLength": 100 }, "company_type": { "description": "company = hiring for itself; consultant = HR/placement consultancy; individual_recruiter", "type": "string", "enum": [ "company", "consultant", "individual_recruiter" ] }, "size": { "description": "Number of employees", "type": "string", "enum": [ "1-10", "10-50", "50+" ] }, "turnover": { "description": "Annual turnover in rupees", "type": "string", "enum": [ "under_2_crore", "2_5_crore", "over_5_crore" ] }, "remove_industries": { "description": "Industry names (from get_company) to remove from the list", "maxItems": 20, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 150 } }, "representative": { "description": "The company's contact person (the site's Company Representative section); name, designation, e-mail and mobile are required by the site, missing ones are taken from the current values", "type": "object", "properties": { "name": { "description": "First and last name, letters only", "type": "string", "maxLength": 50 }, "designation": { "type": "string", "maxLength": 100 }, "email": { "type": "string", "maxLength": 50, "format": "email", "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$" }, "mobile": { "description": "10-digit Indian mobile", "type": "string", "maxLength": 16 }, "landline": { "description": "With STD code, digits only; \"\" clears it", "type": "string", "maxLength": 20 } } }, "city": { "description": "Primary office city in India", "type": "string", "maxLength": 100 }, "address": { "description": "Office address in that city (used only with city)", "type": "string", "maxLength": 1000 }, "name": { "description": "Not changeable by the employer: only send it if the user insists, to get the explanation", "type": "string", "maxLength": 200 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/save_company_location": { "post": { "operationId": "save_company_location", "summary": "Add or edit an office location", "description": "Add an office location to the company page, or edit one by id (from get_company). city must be an Indian city; address is required for a new office. primary=true makes it the main office (sets the company city). Fields not given on an edit stay. Limit 20 company edits a day. Returns the updated company profile.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "description": "Location id to edit; omit to add", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "city": { "description": "Indian city, e.g. Pune (required for a new office)", "type": "string", "maxLength": 100 }, "address": { "description": "Street, building, area (required for a new office)", "type": "string", "maxLength": 500 }, "pincode": { "description": "6-digit PIN code", "type": "string", "maxLength": 10 }, "contact": { "description": "Office phone (10 digits)", "type": "string", "maxLength": 16 }, "email": { "description": "Office e-mail", "type": "string", "maxLength": 50 }, "primary": { "description": "Make this the main office", "type": "boolean" } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/delete_company_location": { "post": { "operationId": "delete_company_location", "summary": "Remove an office location", "description": "Remove one office location from the company page by id (from get_company). Confirm with the employer first.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_my_jobs": { "post": { "operationId": "list_my_jobs", "summary": "List my jobs", "description": "The company's job posts, newest first, 20 per page: id, title, city, type, status (live / closed / under review), posted date, applicant count, views, public url and the applicants page url. status: live (default), closed or all.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "description": "Which jobs (default live)", "type": "string", "enum": [ "live", "closed", "all" ] }, "page": { "description": "Page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 50 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_my_job": { "post": { "operationId": "get_my_job", "summary": "Get one of my jobs", "description": "Full detail of one of the company's jobs: title, status, city, address, type, experience, salary (lakh per year), skills, courses, summary, description (text and HTML), posted date, views, applicant and shortlisted counts, public url, applicants page url and the site's edit page.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/post_job": { "post": { "operationId": "post_job", "summary": "Post a job", "description": "Publish a job on Youth4work (live immediately, same as the site's job form). Show the user the full draft and get a clear yes first. Skills, courses and cities are matched to Youth4work's lists (e.g. \"Java\" -> \"Core Java\", \"Bengaluru\" -> \"Bangalore\"); unknown skills/courses are left out and reported, an unknown city is an error. With 2 cities the site creates one job per city. Experience: years, 0 and 0 = fresher. Salary: rupees lakh per year using the site's bands (0, 0.5, 0.6 ... 1, 1.25 ... 5, 5.5 ... 10, 11 ... 40, and 41 = 40 lakh & above as max); leave both out for 'not disclosed'. Spammy text is rejected. Limit 10 jobs a day; posting the same title again within 10 minutes is refused. Right after posting, Youth4work WorkMails the job to up to 50 best-matching job seekers (skills, city, course, experience, test scores; public profiles that accept e-mail and were active in the last 3 years), within the company's WorkMail plan quota and the daily limit (match_mail \"send\", the defaul", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string", "minLength": 3, "maxLength": 100, "description": "Job title: letters, digits, spaces and - & . ( ) / , + # only" }, "description": { "type": "string", "minLength": 30, "maxLength": 25000, "description": "Role, responsibilities, requirements, benefits. Plain text (blank line = new paragraph) or simple HTML (p, ul, li, strong, em, h3, br)" }, "summary": { "description": "One-line summary shown in job lists", "type": "string", "maxLength": 240 }, "skills": { "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "description": "1-8 skills, e.g. [\"Core Java\", \"Spring\", \"SQL Server\"]" }, "courses": { "description": "Preferred courses/degrees, e.g. [\"B.Tech\", \"MCA\"]", "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "cities": { "description": "1-2 Indian cities, e.g. [\"Pune\"]. Optional for work_from_home", "maxItems": 2, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "addresses": { "description": "Office address for each city, same order (default: the city name)", "maxItems": 2, "type": "array", "items": { "type": "string", "maxLength": 200 } }, "type": { "type": "string", "enum": [ "full_time", "part_time", "internship", "work_from_home" ], "description": "Job type" }, "min_experience": { "description": "Minimum years of experience (0 = fresher, default 0)", "type": "integer", "minimum": 0, "maximum": 40 }, "max_experience": { "description": "Maximum years (0 with min 0 = fresher; default min+2)", "type": "integer", "minimum": 0, "maximum": 40 }, "min_salary_lakhs": { "description": "Minimum salary, rupees lakh per year (site band)", "type": "number", "minimum": 0, "maximum": 41 }, "max_salary_lakhs": { "description": "Maximum salary, rupees lakh per year (site band)", "type": "number", "minimum": 0, "maximum": 41 }, "match_mail": { "description": "WorkMail the new job to up to 50 matching job seekers: \"send\" (default), \"preview\" (list only, nothing sent) or \"off\"", "type": "string", "enum": [ "send", "preview", "off" ] } }, "required": [ "title", "description", "skills", "type" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/mail_matching_talent": { "post": { "operationId": "mail_matching_talent", "summary": "WorkMail a job to matching candidates", "description": "WorkMail one of the company's live jobs to its best-matching job seekers: ranked by matching skills, city (lives there, else wants to work there), course, experience, tested skills, CV and recent activity; at most 50 per job in total (post_job already does this once). Skips people who opted out of e-mail, private or deactivated profiles, accounts inactive 3+ years, people who already applied, and anyone this company mailed about a job in the last 14 days. Uses the company's WorkMail plan quota and the daily limit of 100 WorkMails; every send is logged. dry_run (default true) only returns who WOULD be mailed: show that list and send with dry_run=false only after the employer approves. The message is written from the job (title, city, experience, salary, why the person matches, job link); `message` replaces the opening paragraph. Returns the recipients (profile urls, why each matches), skipped counts, remaining limits and moreMatches (good matches not mailed, for direct contact).\n\nFor: e", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "dry_run": { "description": "true (default) = preview only, nothing sent; false = send", "type": "boolean" }, "message": { "description": "Optional opening paragraph in the employer's words (plain text). The greeting, why they match and the job link are added.", "type": "string", "maxLength": 2000 } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/edit_job": { "post": { "operationId": "edit_job", "summary": "Edit a job", "description": "Change any subset of a live job's description, summary, skills (replaces the list), courses (replaces the list), type, experience, salary or address. Title and city cannot change after posting (site rule): close it and post a new job instead. A closed job must be reopened first. Returns the updated job. Limit 50 job edits/closes/reopens a day.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "description": { "type": "string", "minLength": 30, "maxLength": 25000 }, "summary": { "type": "string", "maxLength": 240 }, "skills": { "description": "New full skill list (1-8)", "minItems": 1, "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "courses": { "description": "New full course list (empty array = none)", "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "type": { "type": "string", "enum": [ "full_time", "part_time", "internship", "work_from_home" ] }, "min_experience": { "type": "integer", "minimum": 0, "maximum": 40 }, "max_experience": { "type": "integer", "minimum": 0, "maximum": 40 }, "min_salary_lakhs": { "type": "number", "minimum": 0, "maximum": 41 }, "max_salary_lakhs": { "type": "number", "minimum": 0, "maximum": 41 }, "address": { "type": "string", "maxLength": 200 } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/close_job": { "post": { "operationId": "close_job", "summary": "Close a job", "description": "Stop a job from appearing in job search (applicants stay visible). Can be undone with reopen_job.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/reopen_job": { "post": { "operationId": "reopen_job", "summary": "Reopen a job", "description": "Make a closed job live again (it shows as newly posted). Jobs under review by Youth4work cannot be reopened.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_applicants": { "post": { "operationId": "list_applicants", "summary": "List applicants", "description": "People who applied to one of the company's jobs, newest first, 20 per page: name, username, headline, city, college, course, graduation year, experience years, top skills with Youth4work scores (tested = verified by a skill test), has resume, applied date, shortlisted, rating, private note and profile url. No contact details: use reveal_candidate_contact or send_workmail.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "page": { "description": "Page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 100 }, "shortlisted_only": { "description": "Only shortlisted applicants", "type": "boolean" } }, "required": [ "job_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/shortlist_applicant": { "post": { "operationId": "shortlist_applicant", "summary": "Shortlist an applicant", "description": "Add an applicant of this job to the shortlist (shortlisted: true, default) or remove them (false). Private to the company; the candidate is not notified.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "username": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Candidate's Youth4work username (from list_applicants, find_matching_candidates or a /y/{username} profile url)" }, "shortlisted": { "description": "true = shortlist (default), false = remove", "type": "boolean" } }, "required": [ "job_id", "username" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/rate_applicant": { "post": { "operationId": "rate_applicant", "summary": "Rate an applicant", "description": "Give an applicant of this job a 1-5 rating and optionally a private note (replaces the previous note). Private to the company.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "username": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Candidate's Youth4work username (from list_applicants, find_matching_candidates or a /y/{username} profile url)" }, "rating": { "type": "integer", "minimum": 1, "maximum": 5, "description": "1 (poor) to 5 (excellent)" }, "note": { "description": "Private note about this applicant", "type": "string", "maxLength": 2000 } }, "required": [ "job_id", "username", "rating" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/find_matching_candidates": { "post": { "operationId": "find_matching_candidates", "summary": "Find matching candidates", "description": "Ranked job seekers with public profiles who match a job (job_id: uses its skills, city and experience) or given skills, 20 per page (up to 10 pages). Any filter you pass overrides the job's. Each result says WHY it matches (matching skills with scores, how many of the skills, city, experience), top skills, education, experience years, whether they have a resume, and alreadyApplied (which of your jobs they applied to). Ranked by number of matching skills, then Youth4work talent score. Present the best few with the reasons; contact only with the employer's approval (send_workmail or reveal_candidate_contact).\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "job_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Job id (from list_my_jobs or post_job)" }, "skills": { "description": "Skill names (required when no job_id)", "maxItems": 8, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "city": { "description": "Indian city where the candidate lives", "type": "string", "maxLength": 100 }, "min_experience": { "description": "Minimum years of experience (by graduation year, as the site filters)", "type": "integer", "minimum": 0, "maximum": 40 }, "max_experience": { "description": "Maximum years (0 with min 0 = freshers / students)", "type": "integer", "minimum": 0, "maximum": 40 }, "course": { "description": "Course/degree, e.g. \"B.Tech\", \"MBA\"", "type": "string", "maxLength": 100 }, "has_resume": { "description": "Only candidates with a resume", "type": "boolean" }, "tested_only": { "description": "Only candidates who took the Youth4work test for a matching skill", "type": "boolean" }, "page": { "description": "Page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 10 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_candidate": { "post": { "operationId": "get_candidate", "summary": "Get a candidate's profile", "description": "The full profile an employer sees on Youth4work, without contact details: headline, about, career aim, city, preferred cities, what they are looking for, education, work experience, all skills with scores and test scores, total experience, verified e-mail/mobile flags, whether a resume exists, last active date, and which of your jobs they applied to (with shortlist/rating). Works for public profiles and for anyone who applied to your jobs.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Candidate's Youth4work username (from list_applicants, find_matching_candidates or a /y/{username} profile url)" } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/reveal_candidate_contact": { "post": { "operationId": "reveal_candidate_contact", "summary": "Reveal candidate contact details", "description": "A candidate's e-mail, mobile and resume url (the contact details Youth4work shows employers on the profile), for contacting them about a real opening. Only when the employer asks for it for a specific candidate; do not reveal in bulk. Works for job seekers with public profiles and for anyone who applied to your jobs. Placeholder or fake mobile numbers are omitted (mobileNote says why). Every reveal is logged and visible to Youth4work; limit 50 different candidates a day. Use the details only for this hiring purpose.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "minLength": 1, "maxLength": 50, "description": "Candidate's Youth4work username (from list_applicants, find_matching_candidates or a /y/{username} profile url)" } }, "required": [ "username" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_assessments": { "post": { "operationId": "list_assessments", "summary": "List my assessments", "description": "The employer's custom assessments (online tests), newest first, 20 per page: id, name, mode (fixed/adaptive), status (draft / ready / live / closed), questions asked, duration in minutes, invited, attempted, and links to the results and invitation pages on youth4work.com. Use it to find an assessment id.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "page": { "description": "Page, 20 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 500 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/search_question_banks": { "post": { "operationId": "search_question_banks", "summary": "Search question banks", "description": "Search the MCQ question banks this employer can build assessment sections from: Youth4work's ready-made skill banks (Java, Sales, Aptitude, Accounting, ...) and the employer's own banks. Returns bank id, name and number of questions. Pass the ids to create_assessment as question_bank_ids, or just pass skills to create_assessment and it picks the best bank itself.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 100, "description": "Skill or topic, e.g. \"java\", \"retail sales\", \"aptitude\"" } }, "required": [ "query" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/create_assessment": { "post": { "operationId": "create_assessment", "summary": "Create an assessment", "description": "Create a custom online assessment for hiring. Optionally fill it straight away with questions from Youth4work's question banks: pass skills (one section per skill, best matching bank) and/or question_bank_ids (from search_question_banks). You can also create it empty and add your own MCQs with add_assessment_questions. Every question has its own timer, so the duration is computed from the questions (there is no overall time limit to set). mode \"fixed\" (default): every candidate gets the same questions, score = % correct. mode \"adaptive\": questions adapt to the candidate's level, ranking by percentile. Names must be unique in the account. Limit 20 new assessments a day. Returns the id, sections, duration and dashboard links.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "minLength": 3, "maxLength": 150, "description": "Assessment name, e.g. \"Inside Sales screening - Oct 2026\"" }, "mode": { "description": "fixed (default) or adaptive", "type": "string", "enum": [ "fixed", "adaptive" ] }, "skills": { "description": "Skills to test with Youth4work question-bank sections, e.g. [\"Java\", \"Aptitude\"]", "maxItems": 10, "type": "array", "items": { "type": "string", "minLength": 2, "maxLength": 100 } }, "question_bank_ids": { "description": "Specific bank ids from search_question_banks", "maxItems": 10, "type": "array", "items": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "questions_per_section": { "description": "Questions asked from each bank section (default 10)", "type": "integer", "minimum": 1, "maximum": 100 }, "show_answers": { "description": "Adaptive mode only: show candidates the right answer after each question (default false)", "type": "boolean" } }, "required": [ "name" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/add_assessment_questions": { "post": { "operationId": "add_assessment_questions", "summary": "Add my own questions", "description": "Add the employer's own multiple-choice questions to an assessment (up to 100 per call, 500 a day). Each question: text, 2 to 6 options, and the 0-based correct_index of the ONE right option (multiple correct answers are not supported). Optional: marks (default 1), seconds allowed for the question (15-600, default 60), difficulty 1-5 (default 3). Questions go into a section (default: named after the assessment), saved in the employer's own question bank, and candidates see options shuffled. Show the employer the questions and answers before adding them. Returns the section, how many were added and the new duration.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" }, "section": { "description": "Section name candidates see, e.g. \"Product knowledge\" (default: the assessment name)", "type": "string", "minLength": 1, "maxLength": 200 }, "questions": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string", "minLength": 3, "maxLength": 2000, "description": "The question" }, "options": { "minItems": 2, "maxItems": 6, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 500 }, "description": "2-6 answer options" }, "correct_index": { "type": "integer", "minimum": 0, "maximum": 5, "description": "0-based position of the right option in options" }, "marks": { "description": "Marks for a correct answer (default 1)", "type": "integer", "minimum": 1, "maximum": 100 }, "seconds": { "description": "Time allowed for this question in seconds (default 60)", "type": "integer", "minimum": 15, "maximum": 600 }, "difficulty": { "description": "1 very easy ... 5 very hard (default 3)", "type": "integer", "minimum": 1, "maximum": 5 } }, "required": [ "text", "options", "correct_index" ] } } }, "required": [ "assessment_id", "questions" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_assessment": { "post": { "operationId": "get_assessment", "summary": "Assessment details", "description": "Everything about one of the employer's assessments: settings, sections, every question with its options and correct answer (up to 300), questions asked, duration, invited/attempted counts, the candidate test page link and how candidates get in, the master passkey (open access code, owner-only), and dashboard links (preview, invitations, results).\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" } }, "required": [ "assessment_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/send_test_link_to_self": { "post": { "operationId": "send_test_link_to_self", "summary": "Send the test invitation to myself", "description": "Send the candidate invitation e-mail for an assessment to the employer's own e-mail address (arrives in about 3-5 minutes) so they see exactly what candidates receive, and return the test link plus a preview page showing every question. Note: employer accounts cannot take tests themselves; to try the full candidate flow, invite a personal e-mail that has a Youth4work job-seeker account. Counts as one invitation. Candidates take tests on ytest.youth4work.com: the company's test page, then 'By Email ID', then sign in to Youth4work (or register free) with the invited e-mail; the test appears. There is no per-person token link, access is tied to the invited e-mail. Only job-seeker accounts can take tests.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" } }, "required": [ "assessment_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/invite_to_assessment": { "post": { "operationId": "invite_to_assessment", "summary": "Invite candidates to an assessment", "description": "Invite people to take an assessment: all applicants of one of the employer's jobs (job_id, optionally shortlisted_only), a list of e-mails (max 200 per call) and/or Youth4work usernames. People already invited (still valid) or who already took it are skipped and listed. send_mode \"youth4work_sends\": Youth4work e-mails each person (from \" via Youth4work\", replies go to the employer's e-mail, sent within ~3-5 minutes). send_mode \"links_only\": invitations are recorded but NOT mailed; the result gives the recipients, subject and message text for the employer's own e-mail tool (e.g. their Gmail) to send from their own address. usernames work only with youth4work_sends. message: optional personal note (plain text, no links; the test link and sign-in steps are added automatically). Limit 500 invitations a day. Confirm the list and the message with the employer first. Candidates take tests on ytest.youth4work.com: the company's test page, then 'By Email ID', then sign in to Youth4work", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" }, "send_mode": { "type": "string", "enum": [ "youth4work_sends", "links_only" ], "description": "Who sends the invitation e-mails" }, "job_id": { "description": "Invite the applicants of this job (one of the employer's jobs)", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 }, "shortlisted_only": { "description": "With job_id: only applicants shortlisted on youth4work.com", "type": "boolean" }, "emails": { "description": "E-mail addresses to invite", "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 150 } }, "usernames": { "description": "Youth4work usernames (job seekers) to invite; youth4work_sends only", "maxItems": 200, "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 } }, "message": { "description": "Personal note for the invitation (plain text, no links)", "type": "string", "maxLength": 2000 }, "subject": { "description": "E-mail subject (default: \"Online assessment from : \")", "type": "string", "maxLength": 150 }, "valid_days": { "description": "Days the invitation stays open (default 7)", "type": "integer", "minimum": 1, "maximum": 60 } }, "required": [ "assessment_id", "send_mode" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_assessment_report": { "post": { "operationId": "get_assessment_report", "summary": "Assessment results", "description": "Results of an assessment: summary (invited, attempted, completed, completion rate, average / median / top percentage, average minutes, score distribution in 20-point buckets) and a page of 25 people: name, username, e-mail, status (completed / started / invited / invitation expired), score (correct answers), maxScore, percentage, section-wise scores with percentile among candidates, rank, time taken, submitted at, webcam snapshot count, and a link to the detailed report on youth4work.com. Completed candidates come first (by rank), then people who have not started.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" }, "page": { "description": "Page, 25 per page (default 1)", "type": "integer", "minimum": 1, "maximum": 1000 }, "sort": { "description": "score (default, best first), recent (latest submissions first) or name", "type": "string", "enum": [ "score", "recent", "name" ] } }, "required": [ "assessment_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_candidate_assessment_result": { "post": { "operationId": "get_candidate_assessment_result", "summary": "One candidate's result", "description": "Detailed result of one person in an assessment: score, percentage, rank, section-wise scores, time taken, webcam snapshot count, and every question answered (their choice, the correct answer, right/wrong, marks, seconds taken). For someone who has not started it returns the invitation status. Typing/subjective/coding parts and proctoring photos are only in the detailed report link.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "assessment_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991, "description": "Assessment id (from list_assessments or create_assessment)" }, "username_or_email": { "type": "string", "minLength": 1, "maxLength": 150, "description": "The candidate's Youth4work username or e-mail, as shown in get_assessment_report" } }, "required": [ "assessment_id", "username_or_email" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/list_plans": { "post": { "operationId": "list_plans", "summary": "List yAccess plans", "description": "The employer's paid plans (yAccess: WorkMails to candidates, full candidate profiles and contacts, job postings) with days, WorkMail quota and price in INR including 18% GST, plus how many WorkMails are left on the current plan and when it ends. Read-only.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": {} } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/create_checkout": { "post": { "operationId": "create_checkout", "summary": "Start buying a plan", "description": "Start buying a yAccess plan for this employer: returns the price (INR, incl. GST) and a pay_url. Only after the employer chose the plan and agreed to the price. Give them the pay_url: they pay on Youth4work's Razorpay page (UPI, cards, net banking); you never pay or see payment details. The plan activates by itself after payment (check with get_checkout). The link works for 2 days.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": true, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "plan_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "string", "maxLength": 20 } ], "description": "plan_id (or code) from list_plans" } }, "required": [ "plan_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/get_checkout": { "post": { "operationId": "get_checkout", "summary": "Checkout status", "description": "One checkout (by checkout_id) or the latest 10: plan, price, status (awaiting_payment, paid, canceled, expired), the pay_url while unpaid, and the plan end date once paid.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_id": { "description": "From create_checkout; omit for the latest 10", "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } } } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } }, "/mcp/api/v1/tools/cancel_checkout": { "post": { "operationId": "cancel_checkout", "summary": "Cancel a checkout", "description": "Cancel an unpaid checkout so its pay link stops working.\n\nFor: employers.", "tags": [ "employer" ], "x-openai-isConsequential": false, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_id": { "type": "integer", "exclusiveMinimum": 0, "maximum": 9007199254740991 } }, "required": [ "checkout_id" ] } } } }, "responses": { "200": { "description": "The tool's result (JSON)", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "description": "Refused or invalid input", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing or expired access token" }, "429": { "description": "Rate limit (120/min per account, 60/min per IP for public tools)" } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } }, "securitySchemes": { "oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://mcp.youth4work.com/authorize", "tokenUrl": "https://mcp.youth4work.com/oauth/token", "refreshUrl": "https://mcp.youth4work.com/oauth/token", "scopes": { "youth4work": "Act on your Youth4work account", "offline_access": "Stay connected (refresh token)" } } } } } } }