# Overview

The Cubit API provides RESTful access to AI job vulnerability intelligence.

## Base URL

```
https://api.maidenlabs.tools
```

All endpoints are relative to this base URL.

## Authentication

All requests (except `/health` and `/schema`) require an API key:

```bash
curl -H "Authorization: Bearer cubit_your_api_key" \
  https://api.maidenlabs.tools/jobs/15-1252.00
```

See [Authentication](/getting-started/authentication.md) for details.

## Response Format

All responses are JSON:

```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
  }
}
```

## Endpoint Groups

| Group                                        | Endpoints                                            | Description                               |
| -------------------------------------------- | ---------------------------------------------------- | ----------------------------------------- |
| [Jobs](/api-reference/jobs.md)               | `/jobs/*`                                            | Job search, profiles, tasks, requirements |
| [Skills](/api-reference/skills.md)           | `/skills/*`                                          | Skill listing, profiles, semantic search  |
| [Regions](/api-reference/regions.md)         | `/regions/*`                                         | MSA-level risk analysis                   |
| [Assessments](/api-reference/assessments.md) | `/assessments/*`, `/jobs/batch`, `/jobs/transitions` | Enterprise scoring and analysis           |
| [Benchmarks](/api-reference/benchmarks.md)   | `/benchmarks/*`                                      | AI benchmark data (Enterprise)            |

## Common Parameters

### Pagination

Endpoints that return lists support:

| Parameter | Type | Default | Description               |
| --------- | ---- | ------- | ------------------------- |
| `limit`   | int  | 10-50   | Maximum results to return |
| `offset`  | int  | 0       | Number of results to skip |

### Sorting

| Parameter    | Type   | Description      |
| ------------ | ------ | ---------------- |
| `sort_by`    | string | Field to sort by |
| `sort_order` | string | `asc` or `desc`  |

## HTTP Status Codes

| Code | Meaning                                           |
| ---- | ------------------------------------------------- |
| 200  | Success                                           |
| 400  | Bad Request - Invalid parameters                  |
| 401  | Unauthorized - Invalid or missing API key         |
| 403  | Forbidden - Insufficient tier for this endpoint   |
| 404  | Not Found - Resource doesn't exist                |
| 422  | Validation Error - Request body validation failed |
| 429  | Rate Limited - Too many requests                  |
| 500  | Server Error - Something went wrong               |

## Error Response Format

```json
{
  "error": "error_code",
  "message": "Human-readable description",
  "details": {
    "field": "additional_context"
  }
}
```

### Error Codes

| Code                  | Description                   |
| --------------------- | ----------------------------- |
| `invalid_api_key`     | API key is invalid or expired |
| `rate_limit_exceeded` | Daily quota exceeded          |
| `insufficient_tier`   | Endpoint requires higher tier |
| `job_not_found`       | SOC code doesn't exist        |
| `region_not_found`    | MSA code doesn't exist        |
| `invalid_request`     | Request validation failed     |

## Rate Limits

| Tier         | Requests/Day | Burst/Minute |
| ------------ | ------------ | ------------ |
| Sandbox      | 100          | 10           |
| Professional | 5,000        | 100          |
| Enterprise   | Unlimited    | 1,000        |

Rate limit headers included in responses:

```
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-01-25T00:00:00Z
```

## Versioning

The current API version is **v1** (implicit in the base URL). Breaking changes will be announced with deprecation periods.

## OpenAPI Specification

Download the OpenAPI 3.0 spec:

```bash
curl https://api.maidenlabs.tools/openapi.json
```

## Utility Endpoints

### Health Check

```http
GET /health
```

No authentication required.

**Response:**

```json
{
  "status": "healthy",
  "version": "2.0.0",
  "timestamp": "2026-01-24T10:30:00Z"
}
```

### Current User

```http
GET /me
```

**Response:**

```json
{
  "tier": "professional",
  "org_name": "Acme EdTech",
  "rate_limit": {
    "daily_limit": 1000,
    "remaining": 847,
    "resets_at": "2026-01-25T00:00:00Z"
  },
  "permissions": {
    "semantic_search": true,
    "task_data": true,
    "regional_data": true,
    "custom_scoring": false,
    "batch_operations": false
  }
}
```

### Schema

```http
GET /schema
```

Returns data schema definitions (dimensions, pillars, scores, quadrants).

### Statistics

```http
GET /stats/overview
```

Returns aggregate statistics about the dataset.

**Response:**

```json
{
  "total_occupations": 923,
  "total_tasks": 18796,
  "total_requirements": 120,
  "total_benchmarks": 13017,
  "quadrant_distribution": {
    "automation": 70,
    "augmentation": 7,
    "protected": 322,
    "transitional": 524
  },
  "methodology_version": "2.0",
  "data_updated": "2026-01-15"
}
```


---

# 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/overview.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.