# SkillsEngine API Documentation

## Version
- **v1** (OAS 3.0)

## Endpoints

### `GET /skills/search`
**Description:** Search skills.

#### Parameters
| Name       | Type     | Location | Description |
|------------|----------|----------|-------------|
| `q`        | `string` | `query`  | Query term (required). |
| `page`     | `integer`| `query`  | Page number (optional). |
| `per_page` | `integer`| `query`  | Results per page (optional). |

#### Responses
- **200:** Success  
  - **Media Type:** `application/json`  
  - **Example Response:**
    ```json
    {
      "skills": [
        {
          "id": "cebeff12-9d07-4402-8c1f-c5aa1be15f70",
          "title": "Connecting Wires",
          "description": "lorem ipsum description",
          "status": "active",
          "source": { "library": "skillsengine:core" },
          "created_at": "2024-07-25T19:49:08.972Z",
          "updated_at": "2024-07-25T19:49:08.972Z"
        }
      ],
      "total_count": 1,
      "page": 1,
      "per_page": 20
    }
    ```

---

### `GET /skill-sets/search`
**Description:** Search skill sets.

#### Parameters
| Name       | Type     | Location | Description |
|------------|----------|----------|-------------|
| `q`        | `string` | `query`  | Query term (required). |
| `page`     | `integer`| `query`  | Page number (optional). |
| `per_page` | `integer`| `query`  | Results per page (optional). |

#### Responses
- **200:** Success  
  - **Media Type:** `application/json`  
  - **Example Response:**
    ```json
    {
      "skill_sets": [
        {
          "id": "a3a74563-ca03-487e-a607-d0238ae69628",
          "title": "Welding",
          "description": "lorem ipsum description",
          "status": "active",
          "source": { "library": "skillsengine:core" },
          "skills": [
            {
              "id": "c45b9807-6607-47c9-a636-549bb4350c92",
              "title": "Work Activity 1",
              "status": "active"
            }
          ]
        }
      ],
      "total_count": 1,
      "page": 1,
      "per_page": 20
    }
    ```

---

### `GET /skill-profiles/search`
**Description:** Search skill profiles.

#### Parameters
| Name       | Type     | Location | Description |
|------------|----------|----------|-------------|
| `q`        | `string` | `query`  | Query term (required). |
| `page`     | `integer`| `query`  | Page number (optional). |
| `per_page` | `integer`| `query`  | Results per page (optional). |

#### Responses
- **200:** Success  
  - **Media Type:** `application/json`  
  - **Example Response:**
    ```json
    {
      "skill_profiles": [
        {
          "id": "4c93252e-befa-4d23-ae51-7bc056e5c322",
          "title": "Electrician",
          "description": "lorem ipsum description of this skill profile",
          "status": "active",
          "source": { "library": "skillsengine:core" },
          "skillsets": [
            {
              "id": "efb38d5b-ce81-4a2c-a498-7c174ad7cce9",
              "title": "Skillset 1",
              "skills": [
                { "id": "e8cd3d2f-2367-403f-b358-871dbae5e2f2", "title": "Work Activity 2" }
              ]
            }
          ]
        }
      ],
      "total_count": 1,
      "page": 1,
      "per_page": 20
    }
    ```

---

### `GET /skill-profiles/{skill_profile_id}`
**Description:** Retrieve details for a specific skill profile.

#### Parameters
| Name               | Type     | Location | Description             |
|--------------------|----------|----------|-------------------------|
| `skill_profile_id` | `string` | `path`   | Skill profile identifier (required). |

#### Responses
- **200:** Success  
  - **Media Type:** `application/json`  
  - **Example Response:**
    ```json
    {
      "id": "71d733d2-0783-4835-b7b3-d2a20c1f09c6",
      "title": "Skill Profile 1",
      "description": "lorem ipsum description of this skill profile",
      "status": "active",
      "skillsets": [
        { "id": "92574fb2-2e9e-4306-b227-f9bc05e5f5bc", "title": "Skillset 2" }
      ]
    }
    ```

---

### `POST /api/translate`
**Description:** Translate input text into a classification and suggestions.

#### Request Body
- **Media Type:** `application/json`  
- **Example:**
  ```json
  { "text": "string" }

#### Responses
- 200: Success
- Media Type: application/json
- Example Response:

  ```json
  {
    "classification": "job_description",
    "suggested_title": "Welder",
    "skillsets": [
      { "id": "49e47d50-ad5f-4f38-ade6-c60737d8e47b", "title": "Welding techniques" }
    ]
  }
  ```

### `GET /skill-profiles`

**Description:** List all skill profiles owned by the user.

#### Parameters
None.

#### Responses
- 200: Success
- Media Type: application/json
- Example Response:

  ```json
  [
    {
      "id": "f3c12c1e-0f15-4386-9ce2-31ea782da3d6",
      "title": "Skill Profile 2",
      "type": "Occupation",
      "owner": "JaineyD",
      "status": "Private"
    }
  ]
  ```