Jobs Assess

`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
Credit Pool: Uses assess-specific credits if configured, otherwise falls back to general credits
Pre-check: Credits are verified before processing the request
Separate Tracking: Assessment operations are tracked separately from other endpoints
Separate Limit: Assess operations can have their own credit limit independent of other endpoints

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

Name	Type	Required	Description
`job_id`	`string`	✅ Yes	The job ID from `/jobs/create`
`github_username`	`string`	✅ Yes	GitHub username to assess (e.g., ‘torvalds’)

Query Parameters

Name	Type	Required	Description
`api_key`	`string`	✅ Yes	API key for authentication (can also be in x-api-key header)
`summary_length`	`integer`	❌ No	Length of generated summary. Default: `1024`, Range: `30-8192`
`context`	`string`	❌ No	Additional context for assessment (max 1024 characters)
`additional_context`	`string`	❌ No	Alias for `context` parameter

Response Headers

Header	Description
`X-Credits-Used`	Total credits used by your API key across all endpoints
`X-Credits-Used-User`	Credits used specifically for /user endpoint
`X-Credits-Used-Search`	Credits used specifically for /jobs/search endpoint
`X-Credits-Used-Assess`	Credits used specifically for /jobs/assess endpoint (increments by 1)
`X-Credits-Remaining`	Remaining general credits (-1 for unlimited accounts)
`X-Credits-Remaining-Search`	Remaining search-specific credits (if configured)
`X-Credits-Remaining-Assess`	Remaining assess-specific credits (if configured)
`X-Calls-User`	Total number of calls made to /user endpoint
`X-Calls-Search`	Total number of calls made to /jobs/search endpoint
`X-Calls-Assess`	Total number of calls made to /jobs/assess endpoint

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:

Field	Type	Range	Description
`fit`	`integer`	0-10	How well the candidate matches the job requirements
`fit_summary`	`string`	-	1-2 sentence explanation referencing specific technologies/repositories
`hireability`	`integer`	0-10	General hireability score based on GitHub presence
`email_copy`	`string`	-	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 Code	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Missing API key
`403`	Forbidden - Invalid API key or access denied to job
`404`	Not Found - Job ID or GitHub username not found
`500`	Internal 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:

Use the email template from email_copy for outreach
Compare fit scores across multiple candidates
Review specific repositories mentioned in fit_summary
Get complete profiles using User Lookup for top candidates
Search for similar profiles using Job Search based on high-scoring candidates

Getting Started

API Reference

Recipes & Examples

Data & Delivery

Example Profiles

Company

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

🔑 Credits

Authentication

URL Parameters

Query Parameters

Response Headers

Response

Assessment Fields

Examples

Assessment AI Features

Error Responses

Usage Notes

Next Steps

Getting Started

API Reference

Recipes & Examples

Data & Delivery

Example Profiles

Company

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

​🔑 Credits

​Authentication

​URL Parameters

​Query Parameters

​Response Headers

​Response

​Assessment Fields

​Examples

​Assessment AI Features

​Error Responses

​Usage Notes

​Next Steps

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

🔑 Credits

Authentication

URL Parameters

Query Parameters

Response Headers

Response

Assessment Fields

Examples

Assessment AI Features

Error Responses

Usage Notes

Next Steps