API Reference

Sessions

Create and manage job application sessions — apply to specific jobs, run one-time searches, or set up recurring autopilot campaigns.

Session Types

Sessions come in three types:

Run Once (Job Array) — Apply to a specific list of job URLs immediately. Best for when users have already selected which jobs they want.

Autopilot Once — One-time automated job search with filters. The system finds matching jobs and applies automatically.

Autopilot Recurring — Scheduled automated applications that run on a configurable schedule (daily, weekly, or monthly).

Create Run Once Session

Apply to a specific list of jobs immediately. Pass the candidate profile ID and an array of up to 100 jobs. When testing with demo profiles, use overrideEmail to receive ATS confirmation emails at your own address.

POST/sessions/apply

Name	Type	Required	Description
`candidateProfileId`	`string`	Required	Profile to use for applications
`searchId`	`string`	Optional	Search record ID from a previous POST /jobs/search response. When provided, the session's searchContext (titles and locations) is populated from that search record.
`overrideEmail`	`string`	Optional	Override the profile's email for this session. Useful with demo profiles so ATS confirmation emails go to your address.

jobsarrayRequired

List of jobs to apply to (max 100)

Field	Type	Required	Description
`companyName`	`string`	Required	Company name
`title`	`string`	Required	Job title
`jobId`	`string`	Required	Your job ID reference
`link`	`string`	Required	Job application URL

curl -X POST https://apply-api.boringproject.ai/api/v1/sessions/apply \
  -H "Authorization: Bearer bp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "candidateProfileId": "prof_xyz789",
    "jobs": [
      {"companyName": "Acme Corp", "title": "Senior Software Engineer", "jobId": "12345", "link": "https://boards.greenhouse.io/acme/jobs/12345"}
    ]
  }'

Response200 OK

{
  "sessionId": "sess_abc123",
  "type": "run_once",
  "userId": "usr_abc123",
  "candidateProfileId": "prof_xyz789",
  "status": "active",
  "stats": { "totalRuns": 1, "totalApplications": 0, "successfulApplications": 0, "failedApplications": 0, "jobsQueued": 1 },
  "searchContext": { "titles": ["Senior Software Engineer"], "locations": [] },
  "createdAt": "2024-02-14T11:00:00Z"
}

Create Autopilot Recurring Session

Set up scheduled automated job search and applications. Configure a schedule pattern, search filters, and application limits.

POST/sessions/autopilot/recurring

curl -X POST https://apply-api.boringproject.ai/api/v1/sessions/autopilot/recurring \
  -H "Authorization: Bearer bp_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "candidateProfileId": "prof_xyz789",
    "schedule": { "pattern": "weekly", "daysOfWeek": ["monday", "wednesday"], "time": "09:00", "timezone": "America/New_York" },
    "filters": { "jobTitle": "Software Engineer", "location": ["San Francisco, CA"], "workType": ["Remote"] },
    "limits": { "maxJobsPerRun": 25 }
  }'

Get Session

Retrieve session details and statistics including total runs, application counts, next scheduled run time, and search context for autopilot sessions.

GET/sessions/:sessionId

Response200 OK

{
  "sessionId": "sess_abc123",
  "type": "autopilot_recurring",
  "userId": "usr_abc123",
  "candidateProfileId": "prof_xyz789",
  "status": "active",
  "stats": { "totalRuns": 15, "totalApplications": 375, "successfulApplications": 320, "failedApplications": 55, "jobsQueued": 25, "lastRunAt": "2024-02-14T09:00:00Z", "nextRunAt": "2024-02-16T09:00:00Z" },
  "searchContext": { "titles": ["Software Engineer"], "locations": ["San Francisco, CA"] },
  "createdAt": "2024-01-15T10:00:00Z"
}

List Sessions

Retrieve a paginated list of all sessions. Filter by status or type to find specific sessions.

GET/sessions

Name	Type	Required	Description
`page`	`integer`	Optional	Page number (default: 1)
`limit`	`integer`	Optional	Items per page, max 100 (default: 20)
`status`	`string`	Optional	Filter: active, paused, completed, cancelled
`type`	`string`	Optional	Filter: run_once, autopilot_recurring

Pause & Resume

Pause a recurring autopilot session to temporarily stop scheduled runs. Resume it later to continue from where it left off.

POST/sessions/:sessionId/pause

# Pause
curl -X POST https://apply-api.boringproject.ai/api/v1/sessions/sess_abc123/pause \
  -H "Authorization: Bearer bp_live_..."

# Resume
curl -X POST https://apply-api.boringproject.ai/api/v1/sessions/sess_abc123/resume \
  -H "Authorization: Bearer bp_live_..."

Get Session Runs

Get execution history for a session. Each run includes stats on jobs found, applications attempted, and success/failure counts.

GET/sessions/:sessionId/runs

Name	Type	Required	Description
`page`	`integer`	Optional	Page number (default: 1)
`limit`	`integer`	Optional	Items per page, max 100 (default: 20)
`status`	`string`	Optional	Filter: in_progress, completed, failed, cancelled

Response200 OK

{
  "data": [{
    "sessionRunId": "run_abc123",
    "sessionId": "sess_abc123",
    "startedAt": "2024-02-14T09:00:00Z",
    "completedAt": "2024-02-14T09:45:00Z",
    "status": "completed",
    "stats": { "jobsFound": 30, "applicationsAttempted": 25, "applicationsSuccessful": 22, "applicationsFailed": 3 }
  }],
  "pagination": { "page": 1, "limit": 20, "total": 15, "totalPages": 1 }
}

Stop Session

Immediately stop a session. Cancels the session, marks any in-progress runs as cancelled, and prevents queued jobs from being processed. Jobs already being processed will finish naturally but no new jobs will be started.

Stopping a session is irreversible. The session status changes to cancelled and cannot be resumed. Use pause/resume for temporary interruptions.

POST/sessions/:sessionId/stop

curl -X POST https://apply-api.boringproject.ai/api/v1/sessions/sess_abc123/stop \
  -H "Authorization: Bearer bp_live_..."

Get Applications by Session

Retrieve individual application results for a specific session. Use the sessionId query parameter on the Applications endpoint to get per-job details including status, errors, and results.

Use this endpoint to show per-job breakdowns on session detail views — which jobs succeeded, which failed, and what errors occurred.

GET/applications?sessionId=sess_abc123

Name	Type	Required	Description
`sessionId`	`string`	Optional	Filter applications by session ID
`status`	`string`	Optional	Filter by status: QUEUED, PROCESSING, SUCCESS, FAILED, CANCELLED
`page`	`integer`	Optional	Page number (default: 1)
`limit`	`integer`	Optional	Items per page, max 100 (default: 20)

Response200 OK

{
  "data": [
    {
      "application_id": "app_abc123",
      "job_url": "https://boards.greenhouse.io/acme/jobs/12345",
      "job_title": "Senior Software Engineer",
      "company_name": "Acme Corp",
      "ats_type": "greenhouse",
      "status": "SUCCESS",
      "candidate_email": "john@example.com",
      "search_id": "srch_abc123",
      "result": { "confirmationUrl": "https://boards.greenhouse.io/acme/jobs/12345/confirmation" },
      "error": null,
      "attempts": [{ "attempt": 1, "status": "success", "timestamp": "2024-02-14T11:05:00Z" }],
      "created_at": "2024-02-14T11:00:00Z",
      "updated_at": "2024-02-14T11:05:00Z"
    }
  ],
  "pagination": { "page": 1, "limit": 20, "total": 5, "totalPages": 1 }
}

Related docs

Sessions

Session Types

Create Run Once Session

Create Autopilot Recurring Session

Get Session

List Sessions

Pause & Resume

Get Session Runs

Stop Session

Get Applications by Session

Continue reading

Candidate Profiles

Usage & Analytics

Rate Limiting