{ "openapi": "3.1.0", "info": { "title": "RankedIn API", "description": "RankedIn analyses LinkedIn data exports and surfaces career scores, network metrics, AI insights, and peer benchmarks. Use this API to retrieve a user's LinkedIn career intelligence.", "version": "1.0.0" }, "servers": [ { "url": "https://rankedin.app" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/api/v1/me": { "get": { "operationId": "getMe", "summary": "Get current user profile", "description": "Returns the authenticated user's profile including name, email, industry, job level, total analyses, and account info.", "responses": { "200": { "description": "User profile", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "email": { "type": "string" }, "name": { "type": "string" }, "tier": { "type": "string" }, "credits": { "type": "number" }, "jobLevel": { "type": "string" }, "industry": { "type": "string" }, "totalAnalyses": { "type": "number" }, "memberSince": { "type": "string", "format": "date-time" } } } } } } } } }, "/api/v1/analyses": { "get": { "operationId": "listAnalyses", "summary": "List all analyses", "description": "Returns a paginated list of the user's LinkedIn analyses. Use this to find analysis IDs for fetching scores, insights, etc.", "parameters": [ { "name": "limit", "in": "query", "description": "Max results to return (default 10, max 50)", "schema": { "type": "integer", "default": 10, "maximum": 50 } }, { "name": "offset", "in": "query", "description": "Number of results to skip for pagination", "schema": { "type": "integer", "default": 0 } } ], "responses": { "200": { "description": "List of analyses", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "overallScore": { "type": "number", "nullable": true } } } }, "meta": { "type": "object", "properties": { "total": { "type": "number" }, "limit": { "type": "number" }, "offset": { "type": "number" } } } } } } } } } } }, "/api/v1/analyses/{id}/scores": { "get": { "operationId": "getScores", "summary": "Get LinkedIn career scores and AI Resilience Score", "description": "Returns overall LinkedIn score (0-100), 8 dimension scores, AI Resilience Score (0-100), and AI risk level. Call this for any question about scores or AI career resilience. Use aiResilienceScore directly — never estimate it from dimensions.", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Analysis ID (use 'latest' shorthand not available — fetch from /analyses first)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Career scores", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "overall": { "type": "number", "description": "Overall LinkedIn score 0-100 (average of 8 dimensions)" }, "aiResilienceScore": { "type": "integer", "nullable": true, "description": "AI Career Resilience Score 0-100. How AI-proof this person's career is. Higher = more resilient. Null if analysis predates this feature." }, "aiRiskLevel": { "type": "string", "nullable": true, "description": "AI risk level: low, medium, or high" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "score": { "type": "number" } } } } } } } } } } } }, "/api/v1/analyses/{id}/network": { "get": { "operationId": "getNetwork", "summary": "Get network metrics", "description": "Returns network statistics including total connections, engagement (reactions/comments), recommendations, endorsements, and growth rate.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Network metrics", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "totalConnections": { "type": "number", "nullable": true }, "connectionsWithEmail": { "type": "number", "nullable": true }, "avgConnectionsPerMonth": { "type": "number", "nullable": true }, "connectionGrowthRate": { "type": "number", "nullable": true }, "totalReactions": { "type": "number", "nullable": true }, "totalComments": { "type": "number", "nullable": true }, "totalMessages": { "type": "number", "nullable": true }, "recommendationsGiven": { "type": "number", "nullable": true }, "recommendationsReceived": { "type": "number", "nullable": true }, "endorsementsGiven": { "type": "number", "nullable": true }, "accountAgeDays": { "type": "number", "nullable": true }, "firstConnectionDate": { "type": "string", "format": "date-time", "nullable": true }, "lastActivityDate": { "type": "string", "format": "date-time", "nullable": true } } } } } } } } }, "/api/v1/analyses/{id}/insights": { "get": { "operationId": "getInsights", "summary": "Get AI-generated career insights and AI Resilience Score", "description": "Returns the AI Resilience Score (0-100, how AI-proof the career is), risk level (low/medium/high), AI action plan (near/medium/long-term), skills to build, AI-vulnerable skills, pivot opportunities, plus career summary, strengths, improvement areas, and recommendations.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "AI insights", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "completedAt": { "type": "string", "format": "date-time" }, "aiResilience": { "type": "object", "nullable": true, "description": "AI Career Resilience analysis. Null if analysis was run before this feature was added.", "properties": { "score": { "type": "integer", "description": "AI Resilience Score 0-100 (higher = more AI-proof career)" }, "riskLevel": { "type": "string", "nullable": true, "description": "Risk level: low, medium, or high" }, "nearTermActions": { "type": "array", "items": { "type": "string" }, "description": "Actions to take in the next 0-6 months" }, "mediumTermActions": { "type": "array", "items": { "type": "string" }, "description": "Actions to take in the next 6-18 months" }, "longTermActions": { "type": "array", "items": { "type": "string" }, "description": "Actions to take in the next 18+ months" }, "skillsToBuild": { "type": "array", "items": { "type": "string" }, "description": "Skills to develop to improve AI resilience" }, "aiVulnerableSkills": { "type": "array", "items": { "type": "string" }, "description": "Current skills at risk of AI automation" }, "pivotOpportunities": { "type": "array", "items": { "type": "string" }, "description": "Career pivot options that are more AI-resilient" } } }, "summary": { "type": "string", "nullable": true }, "strengths": { "type": "array", "items": { "type": "string" } }, "areasForImprovement": { "type": "array", "items": { "type": "string" } }, "recommendations": { "type": "array", "items": { "type": "string" } }, "careerSuggestions": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/v1/analyses/{id}/benchmarks": { "get": { "operationId": "getBenchmarks", "summary": "Get peer benchmarks", "description": "Compares the user's scores against global and peer group averages. Shows percentile rankings, peer group label (e.g. 'Software Engineer in USA'), and per-dimension comparisons.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Peer benchmarks", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "overallGlobalPercentile": { "type": "number" }, "overallPeerPercentile": { "type": "number" }, "peerGroupLabel": { "type": "string" }, "peerGroupSize": { "type": "number" }, "globalCohortSize": { "type": "number" }, "dimensions": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "yourScore": { "type": "number" }, "globalAvg": { "type": "number" }, "globalP75": { "type": "number" }, "globalP90": { "type": "number" }, "globalPercentile": { "type": "number" }, "peerAvg": { "type": "number" }, "peerPercentile": { "type": "number" } } } } } } } } } } } }, "/api/v1/analyses/{id}/career": { "get": { "operationId": "getCareer", "summary": "Get career intelligence", "description": "Returns AI-generated career intelligence from the user's job applications, saved jobs, and career history: career pattern, target role, skill gaps, next steps, and peer pathways.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Career intelligence", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "available": { "type": "boolean" }, "careerPattern": { "type": "string", "nullable": true }, "targetRole": { "type": "string", "nullable": true }, "skillGaps": { "type": "array", "items": { "type": "string" } }, "jobSearchInsights": { "type": "array", "items": { "type": "string" } }, "nextSteps": { "type": "array", "items": { "type": "string" } }, "peerPathways": { "type": "array", "items": { "type": "string" } } } } } } } } } }, "/api/v1/analyses/{id}/connection-changes": { "get": { "operationId": "getConnectionChanges", "summary": "Get connection changes (silent quitters)", "description": "Shows who disconnected from the user, who newly connected, and who changed jobs since the previous analysis. Useful for detecting silent quitters and tracking network changes.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Connection changes", "content": { "application/json": { "schema": { "type": "object", "properties": { "analysisId": { "type": "string" }, "available": { "type": "boolean" }, "disconnectedCount": { "type": "number" }, "newlyConnectedCount": { "type": "number" }, "jobChangesCount": { "type": "number" }, "disconnected": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": "string", "nullable": true }, "linkedinUrl": { "type": "string", "nullable": true } } } }, "newlyConnected": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "company": { "type": "string", "nullable": true }, "linkedinUrl": { "type": "string", "nullable": true } } } }, "jobChanges": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "prevRole": { "type": "string", "nullable": true }, "newRole": { "type": "string", "nullable": true }, "linkedinUrl": { "type": "string", "nullable": true } } } } } } } } } } } } }, "components": { "schemas": {}, "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from RankedIn Settings page. Format: Bearer rkin_..." } } } }