# Jobs

Endpoints for searching, retrieving, and analyzing occupation data.

## Search Jobs

```http
GET /jobs/search
```

Search jobs by keyword (title matching).

**Access:** All tiers

### Parameters

| Parameter              | Type   | Required | Default | Description                                        |
| ---------------------- | ------ | -------- | ------- | -------------------------------------------------- |
| `q`                    | string | Yes      | -       | Search query                                       |
| `limit`                | int    | No       | 10      | Max results (1-50)                                 |
| `exposure_threshold`   | float  | No       | 0.5     | Threshold for "high exposure" quadrant (0.0-1.0)   |
| `imperative_threshold` | float  | No       | 0.5     | Threshold for "high imperative" quadrant (0.0-1.0) |

### Response

```json
{
  "query": "software developer",
  "count": 5,
  "jobs": [
    {
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "automation_susceptibility_score": 47.5,
      "human_centric_resilience_score": 54.7,
      "balanced_impact_score": 7.2,
      "quadrant": "augmentation"
    }
  ]
}
```

### Example

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/jobs/search?q=nurse&limit=5"
```

***

## Semantic Search

```http
GET /jobs/search/semantic
```

Search using natural language queries with AI-powered semantic matching.

**Access:** Professional, Enterprise

### Parameters

| Parameter      | Type   | Required | Default | Description                |
| -------------- | ------ | -------- | ------- | -------------------------- |
| `q`            | string | Yes      | -       | Natural language query     |
| `limit`        | int    | No       | 10      | Max results (1-50)         |
| `search_scope` | string | No       | `jobs`  | `jobs`, `tasks`, or `both` |

### Response

```json
{
  "query": "careers for people who like to argue",
  "count": 10,
  "search_scope": "jobs",
  "jobs": [
    {
      "soc_code": "23-1011.00",
      "title": "Lawyers",
      "relevance_score": 0.87,
      "automation_susceptibility_score": 42.1,
      "human_centric_resilience_score": 67.4,
      "balanced_impact_score": 25.3
    }
  ]
}
```

### Example

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/jobs/search/semantic?q=working+with+animals+outdoors"
```

***

## Get Job Profile

```http
GET /jobs/{soc_code}
```

Get complete profile for a single occupation.

**Access:** All tiers (response depth varies by tier)

### Path Parameters

| Parameter  | Type   | Description                          |
| ---------- | ------ | ------------------------------------ |
| `soc_code` | string | O\*NET SOC code (e.g., "15-1252.00") |

### Query Parameters

| Parameter              | Type  | Required | Default | Description                                        |
| ---------------------- | ----- | -------- | ------- | -------------------------------------------------- |
| `exposure_threshold`   | float | No       | 0.5     | Threshold for "high exposure" quadrant (0.0-1.0)   |
| `imperative_threshold` | float | No       | 0.5     | Threshold for "high imperative" quadrant (0.0-1.0) |

### Response (Sandbox Tier)

```json
{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "scores": {
    "automation_susceptibility_score": 47.5,
    "human_centric_resilience_score": 54.7,
    "balanced_impact_score": 7.2
  },
  "classification": {
    "quadrant": "augmentation",
    "major_group": "15-0000",
    "major_group_label": "Computer and Mathematical Occupations"
  },
  "upgrade_notice": "Upgrade to Professional tier for task-level analysis and keystone skills."
}
```

### Response (Professional/Enterprise)

```json
{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "scores": {
    "automation_susceptibility_score": 47.5,
    "human_centric_resilience_score": 54.7,
    "balanced_impact_score": 7.2,
    "automation_susceptibility_quantile": 0.58,
    "human_centric_resilience_quantile": 0.22
  },
  "pillars": {
    "ai_exposure_potential": 0.475,
    "human_imperative": 0.361,
    "dispositional_resilience": 0.734
  },
  "classification": {
    "quadrant": "augmentation",
    "major_group": "15-0000",
    "major_group_label": "Computer and Mathematical Occupations",
    "minor_group": "15-1200",
    "minor_group_label": "Computer Occupations",
    "broad_group": "15-1250",
    "broad_group_label": "Software and Web Developers",
    "projected_growth": "Much faster than average",
    "projected_job_openings": 125100
  },
  "keystone_skills": [
    {
      "name": "Coordination",
      "type": "Skills",
      "job_relevance": 88.0,
      "ai_resilience": 88.0,
      "combined_impact": 77.4
    }
  ],
  "industries": [
    {"industry": "Computer Systems Design", "percentage": 32.5},
    {"industry": "Software Publishers", "percentage": 18.2}
  ]
}
```

***

## Get Job Tasks

```http
GET /jobs/{soc_code}/tasks
```

Get all tasks for a job with dimension scores.

**Access:** Professional, Enterprise

### Parameters

| Parameter              | Type   | Required | Default                 | Description                                        |
| ---------------------- | ------ | -------- | ----------------------- | -------------------------------------------------- |
| `sort_by`              | string | No       | `ai_exposure_potential` | Sort field                                         |
| `sort_order`           | string | No       | `desc`                  | `asc` or `desc`                                    |
| `limit`                | int    | No       | 50                      | Max results (1-100)                                |
| `include_explanations` | bool   | No       | `true`                  | Include dimension explanations                     |
| `exposure_threshold`   | float  | No       | 0.5                     | Threshold for "high exposure" quadrant (0.0-1.0)   |
| `imperative_threshold` | float  | No       | 0.5                     | Threshold for "high imperative" quadrant (0.0-1.0) |

### Response

```json
{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "task_count": 23,
  "tasks": [
    {
      "task_id": "T1234",
      "task": "Develop and direct software system testing procedures",
      "importance": 4.2,
      "relevance": 85.0,
      "dimensions": {
        "procedural": 7.5,
        "digitization": 9.0,
        "physicality": 1.0,
        "socio_emotional": 3.5
      },
      "pillars": {
        "structural_exposure": 0.82,
        "human_imperative": 0.22,
        "capability_task": 0.68,
        "ai_exposure_potential": 0.72
      },
      "explanations": {
        "procedural": "Testing follows established protocols and can be scripted",
        "digitization": "Entirely digital workflow with automated tooling",
        "physicality": "No physical manipulation required",
        "socio_emotional": "Some coordination with team members required"
      },
      "quadrant": "automation"
    }
  ]
}
```

***

## Get Job Requirements

```http
GET /jobs/{soc_code}/requirements
```

Get skill/ability/knowledge requirements for a job.

**Access:** Professional, Enterprise

### Parameters

| Parameter | Type   | Required | Default       | Description                                  |
| --------- | ------ | -------- | ------------- | -------------------------------------------- |
| `type`    | string | No       | `all`         | `skills`, `abilities`, `knowledge`, or `all` |
| `source`  | string | No       | `diagnostics` | `diagnostics` (full) or `keystone` (top 10)  |
| `limit`   | int    | No       | 20            | Max results                                  |

### Response

```json
{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "requirements": [
    {
      "name": "Programming",
      "element_id": "2.B.3.e",
      "type": "Skills",
      "job_relevance": 9.2,
      "ai_resilience_score": 0.26,
      "benchmark_match_count": 47,
      "benchmark_avg_relevance": 0.72,
      "interpretation": "High relevance, low resilience - core skill under AI pressure"
    }
  ]
}
```

***

## Explain Job

```http
GET /jobs/{soc_code}/explain
```

Get methodology explanation for a job's scores.

**Access:** Professional, Enterprise

### Response

```json
{
  "soc_code": "15-1252.00",
  "title": "Software Developers",
  "methodology_version": "2.0",
  "score_breakdown": {
    "automation_susceptibility_score": {
      "value": 47.5,
      "formula": "ai_exposure_potential x 100",
      "source": "Importance-weighted mean of task-level ai_exposure_potential"
    },
    "human_centric_resilience_score": {
      "value": 54.7,
      "formula": "(human_imperative + dispositional_resilience) / 2 x 100",
      "components": {
        "human_imperative": 0.361,
        "dispositional_resilience": 0.734
      }
    },
    "balanced_impact_score": {
      "value": 7.2,
      "formula": "human_centric_resilience_score - automation_susceptibility_score"
    }
  },
  "task_analysis": {
    "task_count": 23,
    "high_exposure_tasks": 8,
    "protected_tasks": 5
  },
  "data_sources": {
    "tasks": "O*NET 29.0",
    "benchmarks": "HELM v1.13.0",
    "annotations": "GPT-4o-mini (2024-Q4)"
  }
}
```

***

## Compare Jobs

```http
GET /jobs/compare
```

Compare multiple jobs side-by-side.

**Access:** Professional, Enterprise

### Parameters

| Parameter              | Type   | Required | Default | Description                                        |
| ---------------------- | ------ | -------- | ------- | -------------------------------------------------- |
| `socs`                 | string | Yes      | -       | Comma-separated SOC codes (2-10 jobs)              |
| `exposure_threshold`   | float  | No       | 0.5     | Threshold for "high exposure" quadrant (0.0-1.0)   |
| `imperative_threshold` | float  | No       | 0.5     | Threshold for "high imperative" quadrant (0.0-1.0) |

### Example

```bash
curl -H "Authorization: Bearer $API_KEY" \
  "https://api.maidenlabs.tools/jobs/compare?socs=15-1252.00,29-1141.00,43-3031.00"
```

### Response

```json
{
  "comparison": [
    {
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "automation_susceptibility_score": 47.5,
      "human_centric_resilience_score": 54.7,
      "balanced_impact_score": 7.2,
      "quadrant": "augmentation"
    }
  ],
  "skill_overlap_matrix": {
    "15-1252.00": {
      "29-1141.00": 0.35,
      "43-3031.00": 0.42
    }
  }
}
```

***

## Batch Lookup

```http
POST /jobs/batch
```

Retrieve profiles for multiple jobs in a single request.

**Access:** Enterprise only

### Request Body

```json
{
  "soc_codes": ["15-1252.00", "29-1141.00", "43-3031.00"],
  "fields": ["scores", "pillars", "classification"],
  "format": "json"
}
```

### Response

```json
{
  "job_count": 3,
  "fields_included": ["scores", "pillars", "classification"],
  "jobs": [
    {
      "soc_code": "15-1252.00",
      "title": "Software Developers",
      "scores": { ... },
      "pillars": { ... },
      "classification": { ... }
    }
  ]
}
```

***

## Career Transitions

```http
POST /jobs/transitions
```

Find career transition pathways using skill-based similarity.

**Access:** Enterprise only

### Request Body

```json
{
  "source_soc": "43-3031.00",
  "similarity_threshold": 0.70,
  "max_results": 20,
  "filters": {
    "min_resilience_gain": 10,
    "require_positive_growth": true
  }
}
```

### Response

```json
{
  "source_job": {
    "soc_code": "43-3031.00",
    "title": "Bookkeeping, Accounting, and Auditing Clerks",
    "automation_susceptibility_score": 49.3,
    "human_centric_resilience_score": 49.3
  },
  "transition_count": 8,
  "transitions": [
    {
      "target_soc": "13-2011.00",
      "target_title": "Accountants and Auditors",
      "skill_similarity": 0.91,
      "resilience_gain": 11.4,
      "target_resilience_score": 60.7,
      "projected_growth": "Faster than average",
      "overlapping_skills": ["Mathematics", "Critical Thinking"],
      "gap_skills": ["Complex Problem Solving"],
      "transition_difficulty": "low"
    }
  ]
}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.maidenlabs.tools/api-reference/jobs.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.