​
GET /jobs/<job_id>/assess/<github_username>

Assess how well a specific GitHub user fits a stored job description using AI analysis. This endpoint provides detailed AI-powered assessment including job fit scoring, hireability analysis, and personalized outreach email templates.

​
🔑 Credits

  • Cost: 1 credit per assessment (tracked separately from general usage)

​
Authentication

API key can be provided in two ways:
  • Header: x-api-key: YOUR_API_KEY
  • Query parameter: api_key=YOUR_API_KEY

​
URL Parameters

NameTypeRequiredDescription
job_idstring✅ YesThe job ID from /jobs/create
github_usernamestring✅ YesGitHub username to assess (e.g., ‘torvalds’)

​
Query Parameters

NameTypeRequiredDescription
api_keystring✅ YesAPI key for authentication (can also be in x-api-key header)
summary_lengthinteger❌ NoLength of generated summary. Default: 1024, Range: 30-8192
contextstring❌ NoAdditional context for assessment (max 1024 characters)
additional_contextstring❌ NoAlias for context parameter

​
Response Headers

HeaderDescription
X-Credits-UsedTotal credits used by your API key across all endpoints
X-Credits-Used-AssessCredits used specifically for assessment operations (increments by 1)
X-Credits-RemainingRemaining credits (-1 for unlimited accounts)

​
Response

Returns the developer’s complete profile with AI-generated assessment. 
{
  "github_username": "torvalds",
  "fit": 9,
  "fit_summary": "Exceptional fit based on Linux kernel expertise and C programming mastery, directly aligning with systems programming requirements.",
  "hireability":1,
  "email_copy": "Hi Linus, I noticed your incredible work on the Linux kernel and Git version control system. Your expertise in systems programming and C development would be perfect for our infrastructure team. Would you be interested in discussing this opportunity?",
  "email": "torvalds@linux-foundation.org",
  "full_name": "Linus Torvalds",
  "bio": "Creator of Linux and Git",
  "location": "Portland, OR",
  "company": "Linux Foundation",
  "followers": 150000,
  "following": 50,
  "public_repos": 30,
  "hireable": true,
  "summary_text": "Legendary software developer and creator of the Linux operating system...",
  "repos": [
    {
      "full_name": "torvalds/linux",
      "description": "Linux kernel source tree",
      "language": "C",
      "stargazers_count": 150000,
      "fork": false,
      "updated_at": "2025-08-06"
    }
  ],
  "commits": [
    {
      "author_name": "Linus Torvalds",
      "date": "2025-08-05",
      "message": "mm: fix potential race in memory allocation",
      "sha": "abc123..."
    }
  ]
}

​
Assessment Fields

The AI assessment adds these specific fields to the user profile:
FieldTypeRangeDescription
fitinteger0-10How well the candidate matches the job requirements
fit_summarystring-1-2 sentence explanation referencing specific technologies/repositories
hireabilityinteger0-10General hireability score based on GitHub presence
email_copystring-Personalized 2-3 sentence outreach email template

​
Examples

Using cURL 
curl -X GET "https://api.b2d.ai/jobs/550e8400-e29b-41d4-a716-446655440000/assess/torvalds" \
  -H "x-api-key: YOUR_API_KEY"
Using Python 
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"
username = "torvalds"
headers = {"x-api-key": "YOUR_API_KEY"}

# Optional: Add context for better assessment
params = {
    "context": "Remote position, flexible hours",
    "summary_length": 2048
}

response = requests.get(f"https://api.b2d.ai/jobs/{job_id}/assess/{username}", 
                       headers=headers, params=params)

if response.status_code == 200:
    candidate = response.json()
    
    # Display assessment results
    print(f"Candidate: {candidate['full_name']} (@{candidate['github_username']})")
    print(f"Job Fit Score: {candidate['fit']}/10")
    print(f"Hireability Score: {candidate['hireability']}/10")
    print(f"Assessment: {candidate['fit_summary']}")
    print()
    print("Suggested Outreach Email:")
    print(candidate['email_copy'])
    
    # Check assessment credit usage
    assess_credits = int(response.headers.get('X-Credits-Used-Assess', 0))
    total_credits = int(response.headers.get('X-Credits-Used', 0))
    remaining = response.headers.get('X-Credits-Remaining')
    
    print(f"\nCredits - Assessment: {assess_credits}, Total: {total_credits}, Remaining: {remaining}")
else:
    print(f"Error: {response.status_code} - {response.json()}")
Using Python with POST (for complex context) 
import requests

job_id = "550e8400-e29b-41d4-a716-446655440000"
username = "torvalds"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "additional_context": "This is a senior technical leadership role requiring experience with distributed systems and team management. The position offers equity and flexible remote work options.",
    "summary_length": 1500
}

response = requests.post(f"https://api.b2d.ai/jobs/{job_id}/assess/{username}", 
                        headers=headers, json=data)
Raw HTTP Request 
GET https://api.b2d.ai/jobs/550e8400-e29b-41d4-a716-446655440000/assess/torvalds?context=Remote%20position&api_key=YOUR_API_KEY

​
Assessment AI Features

Advanced Analysis:
  • Technology Matching: Identifies specific technologies from candidate’s repositories
  • Experience Weighting: Considers project complexity and contribution history
  • Role Analysis: Distinguishes between maintainers, contributors, and users
  • Impact Assessment: Evaluates repository stars, forks, and community engagement
  • Recency Scoring: Weights recent activity more heavily than older contributions
Personalized Outreach:
  • Repository-Specific: References actual projects and technologies
  • Achievement-Based: Highlights notable accomplishments and contributions
  • Role-Relevant: Connects candidate’s experience to job requirements
  • Professional Tone: Generates appropriate, engaging outreach language

​
Error Responses

Status CodeDescription
400Bad Request - Invalid parameters
401Unauthorized - Missing API key
403Forbidden - Invalid API key or access denied to job
404Not Found - Job ID or GitHub username not found
500Internal Server Error
Example Error Responses: 
{
  "error": "User not found"
}

{
  "error": "Job not found"
}

{
  "error": "context must be less than 1024 characters"
}

​
Usage Notes

Credit Tracking:
  • Assessment credits are tracked separately in the X-Credits-Used-Assess header
  • General X-Credits-Used header includes assessment credits in the total
  • Each successful assessment costs exactly 1 credit
  • Failed assessments (404, 500) do not consume credits
Context Parameter:
  • Provide additional context to improve assessment quality
  • Examples: “Remote position”, “Series A startup”, “Technical leadership role”
  • Limited to 1024 characters
  • Optional but recommended for better results
Performance:
  • Assessment typically takes 3-8 seconds due to AI analysis
  • Results are not cached - each call performs fresh analysis
  • Token usage is logged for cost monitoring

​
Next Steps

After assessing candidates:
  1. Use the email template from email_copy for outreach
  2. Compare fit scores across multiple candidates
  3. Review specific repositories mentioned in fit_summary
  4. Get complete profiles using User Lookup for top candidates
  5. Search for similar profiles using Job Search based on high-scoring candidates