AI API

​

Get AI Insights

curl -X GET "https://api.pipeline.local/api/ai/insights" \
  -H "Authorization: Bearer YOUR_TOKEN"

​

Authentication

​

Planned Features

• Pattern Detection: Identify trends in successful applications (e.g., “Companies with ‘remote-first’ in description have 3x higher response rate”)
• Recommendations: Suggest high-potential jobs based on match score and historical success
• Market Analysis: Compare your application stats to anonymized aggregate data
• Success Prediction: Estimate likelihood of getting an interview based on job characteristics

​

Query Parameters (Planned)

​

Response (Planned)

​

Example Response (Planned)

{
  "insights": [
    {
      "id": "ins_001",
      "user_id": "user_abc123",
      "insight_type": "pattern_detection",
      "title": "Remote jobs have higher response rates",
      "content": "Jobs marked as remote receive responses 2.3x faster (avg 4.2 days vs 9.7 days). Consider prioritizing remote positions.",
      "metadata": {
        "confidence": 0.87,
        "sample_size": 24,
        "remote_response_time": 4.2,
        "non_remote_response_time": 9.7
      },
      "created_at": "2026-03-04T08:00:00Z"
    },
    {
      "id": "ins_002",
      "insight_type": "recommendation",
      "title": "3 high-potential jobs match your profile",
      "content": "Based on your experience, these positions have 85%+ match scores and are from companies with fast response times.",
      "metadata": {
        "recommended_job_ids": ["job_001", "job_002", "job_003"],
        "avg_match_score": 88.3
      },
      "created_at": "2026-03-04T08:00:00Z"
    }
  ],
  "has_more": false
}

​

Implementation Plan

1. Fetch user’s jobs + events from database
2. Build structured prompt with:
   • Job data (company, title, status, timestamps)
   • Application patterns (success rate by source, response times)
   • Recent activity
3. Call Gemini API with few-shot examples
4. Parse response and store in insights table
5. Return cached insights if fresh (< 1 hour old)

​

Status: ❌ Not Implemented

{
  "error": "Not implemented"
}

​

Generate Digest

curl -X GET "https://api.pipeline.local/api/ai/digest" \
  -H "Authorization: Bearer YOUR_TOKEN"

​

Authentication

​

Planned Features

• Daily Digest: Summary of yesterday’s activity (applications sent, responses received, upcoming interviews)
• Weekly Summary: Week in review with stats and insights
• Smart Prioritization: Highlight time-sensitive actions (e.g., “3 applications need follow-up”)
• Encouragement: Motivational messaging based on progress

​

Query Parameters (Planned)

​

Response (Planned)

​

Example Response (Planned)

{
  "insight": {
    "id": "ins_daily_2026_03_04",
    "user_id": "user_abc123",
    "insight_type": "daily_digest",
    "title": "Your Daily Job Search Update",
    "content": "## Yesterday's Highlights\n\n✅ **2 applications sent**\n- Acme Corp — Senior Backend Engineer\n- TechCo — Full Stack Developer\n\n📩 **1 response received**\n- BestStartup replied to your application (7 days)\n\n📅 **Upcoming**\n- Phone screen with Acme Corp tomorrow at 2 PM\n\n## Recommendations\n\n3 new high-match jobs were posted (avg score: 86%). Consider applying soon.\n\n---\n\n*Keep up the momentum! You're 15% ahead of last week's pace.*",
    "metadata": {
      "stats": {
        "applications_sent": 2,
        "responses_received": 1,
        "upcoming_interviews": 1
      },
      "recommendations_count": 3
    },
    "created_at": "2026-03-04T08:00:00Z"
  }
}

​

Implementation Plan

1. Fetch recent events (last 24h for daily, 7d for weekly)
2. Aggregate stats:
   • Applications sent
   • Status changes
   • Upcoming interviews (from interview_at field)
   • Response times
3. Build structured prompt with context
4. Call Claude API for natural language generation
5. Store generated digest in insights table
6. Optionally send via Discord webhook or email

​

Status: ❌ Not Implemented

{
  "error": "Not implemented"
}

​

Job Scoring (Planned)

​

When Jobs Are Scored

1. New job created — Scored asynchronously after creation
2. Job updated — Re-scored if description or requirements change
3. Manual trigger — User can request re-scoring from UI

​

Scoring Algorithm (Planned)

• Job description
• Company name
• User’s profile (extracted from past applications)
• User’s resume (if uploaded)

• ai_match_score (0-100)
• ai_reasoning (explanation)
• ai_parsed_data (extracted skills, salary, experience level)

You are an expert career advisor. Analyze this job posting and rate its fit for the candidate.

Job:
Title: {job_title}
Company: {company_name}
Description: {job_description}

Candidate Profile:
{user_profile}

Provide:
1. Match score (0-100)
2. Reasoning (2-3 sentences)
3. Extracted data (skills, salary range, experience level)

​

Database Updates

• jobs.ai_match_score
• jobs.ai_reasoning
• jobs.ai_parsed_data
• Creates ai_scored event

​

Status: ❌ Not Implemented

​

Errors

​

Common Errors (Planned)

• 401 Unauthorized — Missing or invalid auth token
• 429 Rate Limited — Exceeded 20 requests/hour limit
• 500 AI Service Error — Gemini/Claude API error
• 501 Not Implemented — Current stub response
• 503 Service Unavailable — AI service temporarily down

​

Example Error Response

{
  "error": {
    "code": "AI_SERVICE_ERROR",
    "message": "Failed to generate insight. Please try again."
  }
}

​

Rate Limiting

• Standard Users: 20 requests/hour
• Reset: Top of each hour (UTC)
• Headers: Rate limit info included in response:
  X-RateLimit-Limit: 20
  X-RateLimit-Remaining: 15
  X-RateLimit-Reset: 1709550000
  

​

Exceeding Limits

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "You have exceeded your hourly limit for AI requests. Try again in 23 minutes."
  }
}

​

Implementation Timeline

• API keys (Google AI, Anthropic)
• Jobs API must be complete first
• User profile data for personalization