# Scoutly API Documentation

## Overview

The Scoutly API allows you to programmatically access all the core functionality of the Scoutly platform using API keys. This enables you to integrate Scoutly's recruitment and hiring automation features into your own applications and workflows.

## Authentication

All API requests must include an API key in the Authorization header:

```
Authorization: Bearer sk_live_YOUR_API_KEY_HERE
```

### API Key Types
- **Live Keys**: `sk_live_...` - For production use
- **Test Keys**: `sk_test_...` - For development and testing

### Getting API Keys
1. Go to User Settings (`/static/user-settings/`)
2. Navigate to the API Keys section
3. Click "Generate API Key"
4. Copy and securely store your API key

**Note**: API keys are organization-scoped and only return data for your organization.

## Base URL

All API endpoints are available at: `https://your-domain.com/api/`

## Core API Endpoints

### 1. Job Management

#### Create Job
```http
POST /api/jobs
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "title": "Software Engineer",
  "description": "We are looking for a talented software engineer...",
  "location": "Remote",
  "salary_range": "$80,000 - $120,000",
  "requirements": "Bachelor's degree in Computer Science...",
  "benefits": "Health insurance, 401k, flexible hours..."
}
```

#### Get All Jobs
```http
GET /api/jobs
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Single Job
```http
GET /api/jobs/{job_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Update Job
```http
PUT /api/jobs/{job_id}
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "title": "Updated Job Title",
  "description": "Updated description..."
}
```

#### Delete Job
```http
DELETE /api/jobs/{job_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Disable Job
```http
POST /api/jobs/{job_id}/disable
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 2. Applicant Management

#### Get Applications for Job
```http
GET /api/jobs/{job_id}/applications
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Applicants Count
```http
GET /api/applicants/count
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Update Application Stage
```http
POST /api/applications/{application_id}/stage
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "stage": "screening",
  "notes": "Moving to next stage"
}
```

#### Download Resume
```http
GET /api/applications/{application_id}/resume
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 3. Interview Management

#### Schedule Technical Interview
```http
POST /api/calendar/schedule-technical
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "application_id": 123,
  "datetime": "2025-07-25T14:00:00Z",
  "duration_minutes": 60
}
```

#### Get Scheduled Meetings
```http
GET /api/calendar/meetings
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Cancel Meeting
```http
DELETE /api/calendar/meetings/{meeting_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Reschedule Meeting
```http
PUT /api/calendar/meetings/{meeting_id}/reschedule
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "new_datetime": "2025-07-26T15:00:00Z"
}
```

#### Get Available Slots
```http
GET /api/calendar/available-slots?days_ahead=14
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Set Availability
```http
POST /api/calendar/availability
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "day_of_week": 1,
  "start_time": "09:00",
  "end_time": "17:00",
  "date": "2025-07-25"
}
```

### 4. Calendar Integration

#### Get Calendar Status
```http
GET /api/calendar/status
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Calendar Auth URL
```http
GET /api/calendar/auth-url
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 5. Document Management

#### Upload Documents
```http
POST /api/documents/upload
Content-Type: multipart/form-data
Authorization: Bearer sk_live_YOUR_API_KEY

Form data:
- file: [PDF file]
- application_id: 123
- document_type: "contract"
```

#### List Documents
```http
GET /api/documents?application_id=123
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Download Document
```http
GET /api/documents/{document_id}/download
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Delete Document
```http
DELETE /api/documents/{document_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 6. Personality Tests

#### Get Personality Tests
```http
GET /api/personality-tests
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Create Personality Test
```http
POST /api/personality-tests
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "name": "Technical Assessment",
  "description": "Assessment for technical roles",
  "questions": [
    {
      "question": "How do you approach problem-solving?",
      "options": ["Methodically", "Creatively", "Collaboratively", "Analytically"]
    }
  ]
}
```

#### Get Test Results
```http
GET /api/personality-tests/{test_id}/results
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Associate Test with Job
```http
POST /api/jobs/{job_id}/tests/{test_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 7. Dashboard & Analytics

#### Get Dashboard Overview
```http
GET /api/dashboard/overview
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Interview Pipeline
```http
GET /api/dashboard/pipeline
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Time Analytics
```http
GET /api/dashboard/analytics/time
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Search Jobs
```http
GET /api/dashboard/search?q=engineer&status=active
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 8. AI & Resume Processing

#### AI Review Resume
```http
POST /api/resume/ai-review
Content-Type: multipart/form-data
Authorization: Bearer sk_live_YOUR_API_KEY

Form data:
- resume: [PDF file]
- job_id: 123
```

#### Match Resume to Job
```http
POST /api/resume/match
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "resume_text": "Software engineer with 5 years experience...",
  "job_description": "Looking for experienced developer..."
}
```

#### Generate Job Description
```http
POST /api/generate-job
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "prompt": "Create a job description for a senior React developer"
}
```

### 9. Hiring Automation

#### Move to Hiring Phase
```http
POST /api/hiring/move-to-hiring
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "application_id": 123
}
```

#### Send Reference Check
```http
POST /api/hiring/reference-check/{application_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Send Job Offer
```http
POST /api/hiring/job-offer/{application_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Hiring Status
```http
GET /api/hiring/status/{application_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 10. Organization Management

#### Get Organization Details
```http
GET /api/organization
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get Organization Users
```http
GET /api/organization/users
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Invite User
```http
POST /api/organization/invite
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "email": "user@example.com",
  "role": "recruiter"
}
```

### 11. Social Media Management

#### Generate Social Media Post
```http
POST /api/social-media/generate
Content-Type: application/json
Authorization: Bearer sk_live_YOUR_API_KEY

{
  "prompt": "Create a post about our new job opening",
  "style": "professional_3d"
}
```

#### Get Social Media Posts
```http
GET /api/social-media/posts
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Approve Social Media Post
```http
POST /api/social-media/posts/{post_id}/approve
Authorization: Bearer sk_live_YOUR_API_KEY
```

### 12. API Key Management

#### List API Keys
```http
GET /api/api-keys
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Get API Usage Stats
```http
GET /api/api-keys/stats
Authorization: Bearer sk_live_YOUR_API_KEY
```

#### Delete API Key
```http
DELETE /api/api-keys/{key_id}
Authorization: Bearer sk_live_YOUR_API_KEY
```

## Response Formats

All API responses are in JSON format. Successful responses typically include:

```json
{
  "id": 123,
  "title": "Software Engineer",
  "description": "Job description...",
  "created_at": "2025-07-23T10:00:00Z",
  "updated_at": "2025-07-23T10:00:00Z"
}
```

Error responses include:

```json
{
  "detail": "Error message describing what went wrong"
}
```

## Rate Limiting

API requests are rate-limited per organization:
- **Standard**: 1000 requests per hour
- **Premium**: 5000 requests per hour

Rate limit headers are included in responses:
- `X-RateLimit-Limit`: Total requests allowed
- `X-RateLimit-Remaining`: Requests remaining
- `X-RateLimit-Reset`: Time when limit resets

## Organization-Based Access Control

All API endpoints automatically filter data based on your organization:
- You can only access jobs, applicants, and data from your organization
- API keys are tied to the organization of the user who created them
- Cross-organization access is not permitted

## Error Codes

- `200` - Success
- `201` - Created
- `400` - Bad Request
- `401` - Unauthorized (invalid API key)
- `403` - Forbidden (insufficient permissions)
- `404` - Not Found
- `429` - Rate Limit Exceeded
- `500` - Internal Server Error

## SDKs and Libraries

### Python Example
```python
import requests

headers = {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
}

# Create a job
job_data = {
    'title': 'Software Engineer',
    'description': 'We are looking for...'
}

response = requests.post(
    'https://your-domain.com/api/jobs',
    headers=headers,
    json=job_data
)

print(response.json())
```

### JavaScript Example
```javascript
const headers = {
    'Authorization': 'Bearer sk_live_YOUR_API_KEY',
    'Content-Type': 'application/json'
};

// Get all jobs
fetch('https://your-domain.com/api/jobs', {
    headers: headers
})
.then(response => response.json())
.then(data => console.log(data));
```

### cURL Example
```bash
# Create a job
curl -X POST https://your-domain.com/api/jobs \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Software Engineer",
    "description": "We are looking for a talented engineer..."
  }'
```

## Webhooks (Coming Soon)

Webhook support for real-time notifications about:
- New applications
- Stage changes
- Interview completions
- Document uploads

## Support

For API support, please contact our development team or refer to the in-app documentation.

---

**Note**: This API is designed to provide programmatic access to all Scoutly features while maintaining the same security and organization-based access controls as the web interface.